Função SQLGetFunctions
Conformidade
Versão introduzida: Conformidade de padrões do ODBC 1.0: ISO 92
Resumo
SQLGetFunctions retorna informações sobre se um driver dá suporte a uma função ODBC específica. Essa função é implementada no Gerenciador de Driver; ele também pode ser implementado em drivers. Se um driver implementar SQLGetFunctions, o Gerenciador de Driver chamará a função no driver. Caso contrário, ele executará a função em si.
Sintaxe
SQLRETURN SQLGetFunctions(
SQLHDBC ConnectionHandle,
SQLUSMALLINT FunctionId,
SQLUSMALLINT * SupportedPtr);
Argumentos
ConnectionHandle
[Entrada] Identificador de conexão.
Functionid
[Entrada] Um valor #define que identifica a função ODBC de interesse; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS.
SQL_API_ODBC3_ALL_FUNCTIONS é usado por um aplicativo ODBC 3*.x* para determinar o suporte a funções ODBC 3*.x* e anteriores.
SQL_API_ALL_FUNCTIONS é usado por um aplicativo ODBC 2*.x* para determinar o suporte de funções ODBC 2*.x* e anteriores.
Para obter uma lista de valores #define que identificam funções ODBC, consulte as tabelas em "Comentários".
SupportedPtr
[Saída] Se FunctionId identificar uma única função ODBC, SupportedPtr apontará para um único valor SQLUSMALLINT que será SQL_TRUE se a função especificada tiver suporte do driver e SQL_FALSE se não houver suporte.
Se FunctionId for SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr apontará para uma matriz SQLSMALLINT com vários elementos iguais a SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Essa matriz é tratada pelo Gerenciador de Driver como um bitmap de 4.000 bits que pode ser usado para determinar se há suporte para uma função ODBC 3*.x* ou anterior. A macro SQL_FUNC_EXISTS é chamada para determinar o suporte à função. (Confira "Comentários".) Um aplicativo ODBC 3*.x* pode chamar SQLGetFunctions com SQL_API_ODBC3_ALL_FUNCTIONS em um driver ODBC 3*.x* ou ODBC 2*.x*.
Se FunctionId for SQL_API_ALL_FUNCTIONS, SupportedPtr apontará para uma matriz SQLUSMALLINT de 100 elementos. A matriz é indexada por valores #define usados pelo FunctionId para identificar cada função ODBC; alguns elementos da matriz são não utilizados e reservados para uso futuro. Um elemento será SQL_TRUE se identificar uma função ODBC 2*.x* ou anterior compatível com o driver. Ele será SQL_FALSE se identificar uma função ODBC sem suporte pelo driver ou não identificar uma função ODBC.
As matrizes retornadas em *SupportedPtr usam indexação baseada em zero.
Retornos
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.
Diagnósticos
Quando SQLGetFunctions retorna SQL_ERROR ou SQL_SUCCESS_WITH_INFO, um valor SQLSTATE associado pode ser obtido chamando SQLGetDiagRec com um HandleType de SQL_HANDLE_DBC e um Identificador de ConnectionHandle. A tabela a seguir lista os valores SQLSTATE normalmente retornados por SQLGetFunctions e explica cada um deles no contexto dessa função; a notação "(DM)" precede as descrições de SQLSTATEs retornadas pelo Gerenciador de Driver. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado o contrário.
| SQLSTATE | Erro | Descrição |
|---|---|---|
| 01000 | Aviso geral | Mensagem informativa específica do driver. (A função retorna SQL_SUCCESS_WITH_INFO.) |
| 08S01 | Falha no link de comunicação | O link de comunicação entre o driver e a fonte de dados à qual o driver foi conectado falhou antes da função concluir o processamento. |
| HY000 | Erro geral | Ocorreu um erro para o qual não havia nenhum SQLSTATE específico e para o qual nenhum SQLSTATE específico da implementação foi definido. A mensagem de erro retornada por SQLGetDiagRec no buffer *MessageText descreve o erro e sua causa. |
| HY001 | Erro de alocação de memória | O driver não pôde alocar a memória necessária para dar suporte à execução ou à conclusão da função. |
| HY010 | Erro de sequência de funções | (DM) SQLGetFunctions foi chamado antes de SQLConnect, SQLBrowseConnect ou SQLDriverConnect. (DM) SQLBrowseConnect foi chamado para o ConnectionHandle e retornou SQL_NEED_DATA. Essa função foi chamada antes de SQLBrowseConnect retornar SQL_SUCCESS_WITH_INFO ou SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect ou SQLMoreResults foi chamado para ConnectionHandle e retornado SQL_PARAM_DATA_AVAILABLE. Essa função foi chamada antes de os dados serem recuperados para todos os parâmetros transmitidos. |
| HY013 | Erro de gerenciamento de memória | A chamada de função não pôde ser processada porque os objetos de memória subjacentes não puderam ser acessados, possivelmente devido a condições de memória baixa. |
| HY095 | Tipo de função fora do intervalo | (DM) Um valor FunctionId inválido foi especificado. |
| HY117 | A conexão está suspensa devido ao estado de transação desconhecido. Somente funções desconectar e somente leitura são permitidas. | (DM) Para obter mais informações sobre o estado suspenso, consulte Função SQLEndTran. |
| HYT01 | O tempo limite da conexão expirou | O período de tempo limite da conexão expirou antes da fonte de dados responder à solicitação. O período de tempo limite da conexão é definido por meio de SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT. |
Comentários
SQLGetFunctions sempre retorna que HÁ suporte para SQLGetFunctions, SQLDataSources e SQLDrivers . Ele faz isso porque essas funções são implementadas no Gerenciador de Driver. O Gerenciador de Driver mapeará uma função ANSI para a função Unicode correspondente se a função Unicode existir e mapeará uma função Unicode para a função ANSI correspondente se a função ANSI existir. Para obter informações sobre como os aplicativos usam SQLGetFunctions, consulte Níveis de conformidade da interface.
Veja a seguir uma lista de valores válidos para FunctionId para funções que estão em conformidade com o nível de conformidade de padrões ISO 92:
| Valor de FunctionId | Valor de FunctionId |
|---|---|
| SQL_API_SQLALLOCHANDLE | SQL_API_SQLGETDESCFIELD |
| SQL_API_SQLBINDCOL | SQL_API_SQLGETDESCREC |
| SQL_API_SQLCANCEL | SQL_API_SQLGETDIAGFIELD |
| SQL_API_SQLCLOSECURSOR | SQL_API_SQLGETDIAGREC |
| SQL_API_SQLCOLATTRIBUTE | SQL_API_SQLGETENVATTR |
| SQL_API_SQLCONNECT | SQL_API_SQLGETFUNCTIONS |
| SQL_API_SQLCOPYDESC | SQL_API_SQLGETINFO |
| SQL_API_SQLDATASOURCES | SQL_API_SQLGETSTMTATTR |
| SQL_API_SQLDESCRIBECOL | SQL_API_SQLGETTYPEINFO |
| SQL_API_SQLDISCONNECT | SQL_API_SQLNUMRESULTCOLS |
| SQL_API_SQLDRIVERS | SQL_API_SQLPARAMDATA |
| SQL_API_SQLENDTRAN | SQL_API_SQLPREPARE |
| SQL_API_SQLEXECDIRECT | SQL_API_SQLPUTDATA |
| SQL_API_SQLEXECUTE | SQL_API_SQLROWCOUNT |
| SQL_API_SQLFETCH | SQL_API_SQLSETCONNECTATTR |
| SQL_API_SQLFETCHSCROLL | SQL_API_SQLSETCURSORNAME |
| SQL_API_SQLFREEHANDLE | SQL_API_SQLSETDESCFIELD |
| SQL_API_SQLFREESTMT | SQL_API_SQLSETDESCREC |
| SQL_API_SQLGETCONNECTATTR | SQL_API_SQLSETENVATTR |
| SQL_API_SQLGETCURSORNAME | SQL_API_SQLSETSTMTATTR |
| SQL_API_SQLGETDATA |
Veja a seguir uma lista de valores válidos para FunctionId para funções em conformidade com o nível de conformidade de padrões do Grupo Aberto:
| Valor FunctionId | Valor FunctionId |
|---|---|
| SQL_API_SQLCOLUMNS | SQL_API_SQLSTATISTICS |
| SQL_API_SQLSPECIALCOLUMNS | SQL_API_SQLTABLES |
Veja a seguir uma lista de valores válidos para FunctionId para funções em conformidade com o nível de conformidade de padrões ODBC.
| Valor FunctionId | Valor FunctionId |
|---|---|
| SQL_API_SQLBINDPARAMETER | SQL_API_SQLNATIVESQL |
| SQL_API_SQLBROWSECONNECT | SQL_API_SQLNUMPARAMS |
| SQL_API_SQLBULKOPERATIONS[1] | SQL_API_SQLPRIMARYKEYS |
| SQL_API_SQLCOLUMNPRIVILEGES | SQL_API_SQLPROCEDURECOLUMNS |
| SQL_API_SQLDESCRIBEPARAM | SQL_API_SQLPROCEDURES |
| SQL_API_SQLDRIVERCONNECT | SQL_API_SQLSETPOS |
| SQL_API_SQLFOREIGNKEYS | SQL_API_SQLTABLEPRIVILEGES |
| SQL_API_SQLMORERESULTS |
[1] Ao trabalhar com um driver ODBC 2*.x*, SQLBulkOperations será retornado como compatível somente se ambos os seguintes forem verdadeiros: o driver ODBC 2*.x* dá suporte a SQLSetPos e o tipo de informação SQL_POS_OPERATIONS retorna o bit SQL_POS_ADD como definido.
Veja a seguir uma lista de valores válidos para FunctionId para funções introduzidas no ODBC 3.8 ou posterior:
| Valor FunctionId |
|---|
| SQL_API_SQLCANCELHANDLE [2] |
[2] SQLCancelHandle será retornado como compatível somente se o driver der suporte a SQLCancel e SQLCancelHandle. Se o SQLCancel tiver suporte, mas o SQLCancelHandle não for, o aplicativo ainda poderá chamar SQLCancelHandle em um identificador de instrução, pois ele será mapeado para SQLCancel.
SQL_FUNC_EXISTS Macro
A macro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) é usada para determinar o suporte de funções ODBC 3*.x* ou anteriores depois que SQLGetFunctions tiver sido chamado com um argumento FunctionId de SQL_API_ODBC3_ALL_FUNCTIONS. O aplicativo chama SQL_FUNC_EXISTS com o argumento SupportedPtr definido como SupportedPtr passado em SQLGetFunctions e com o argumento FunctionID definido como o #define para a função. SQL_FUNC_EXISTS retornará SQL_TRUE se a função tiver suporte e SQL_FALSE caso contrário.
Observação
Ao trabalhar com um driver ODBC 2*.x*, O Gerenciador de Driver ODBC 3*.x* retornará SQL_TRUE para SQLAllocHandle e SQLFreeHandle porque SQLAllocHandle é mapeado para SQLAllocEnv, SQLAllocConnect ou SQLAllocStmt e porque SQLFreeHandle é mapeado para SQLFreeEnv, SQLFreeConnect ou SQLFreeStmt. SQLAllocHandle ou SQLFreeHandle com um argumento HandleType de SQL_HANDLE_DESC não tem suporte, no entanto, mesmo que SQL_TRUE seja retornado para as funções, porque não há nenhuma função ODBC 2*.x* para a qual mapear nesse caso.
Exemplo de código
Os três exemplos a seguir mostram como um aplicativo usa SQLGetFunctions para determinar se um driver dá suporte a SQLTables, SQLColumns e SQLStatistics. Se o driver não der suporte a essas funções, o aplicativo se desconectará do driver. O primeiro exemplo chama SQLGetFunctions uma vez para cada função.
SQLUSMALLINT TablesExists, ColumnsExists, StatisticsExists;
RETCODE retcodeTables, retcodeColumns, retcodeStatistics
retcodeTables = SQLGetFunctions(hdbc, SQL_API_SQLTABLES, &TablesExists);
retcodeColumns = SQLGetFunctions(hdbc, SQL_API_SQLCOLUMNS, &ColumnsExists);
retcodeStatistics = SQLGetFunctions(hdbc, SQL_API_SQLSTATISTICS, &StatisticsExists);
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.
if (retcodeTables == SQL_SUCCESS && TablesExists == SQL_TRUE &&
retcodeColumns == SQL_SUCCESS && ColumnsExists == SQL_TRUE &&
retcodeStatistics == SQL_SUCCESS && StatisticsExists == SQL_TRUE)
{
// Continue with application
}
SQLDisconnect(hdbc);
No segundo exemplo, um aplicativo ODBC 3.x chama SQLGetFunctions e passa uma matriz na qual SQLGetFunctions retorna informações sobre todas as funções ODBC 3.x e anteriores.
RETCODE retcodeTables, retcodeColumns, retcodeStatistics
SQLUSMALLINT fExists[SQL_API_ODBC3_ALL_FUNCTIONS_SIZE];
retcode = SQLGetFunctions(hdbc, SQL_API_ODBC3_ALL_FUNCTIONS, fExists);
// SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver.
if (retcode == SQL_SUCCESS &&
SQL_FUNC_EXISTS(fExists, SQL_API_SQLTABLES) == SQL_TRUE &&
SQL_FUNC_EXISTS(fExists, SQL_API_SQLCOLUMNS) == SQL_TRUE &&
SQL_FUNC_EXISTS(fExists, SQL_API_SQLSTATISTICS) == SQL_TRUE)
{
// Continue with application
}
SQLDisconnect(hdbc);
O terceiro exemplo é um aplicativo ODBC 2.x que chama SQLGetFunctions e passa uma matriz de 100 elementos em que SQLGetFunctions retorna informações sobre todas as funções ODBC 2.x e anteriores.
#define FUNCTIONS 100
RETCODE retcodeTables, retcodeColumns, retcodeStatistics
SQLUSMALLINT fExists[FUNCTIONS];
retcode = SQLGetFunctions(hdbc, SQL_API_ALL_FUNCTIONS, fExists);
/* SQLGetFunctions is completed successfully and SQLTables, SQLColumns, and SQLStatistics are supported by the driver. */
if (retcode == SQL_SUCCESS &&
fExists[SQL_API_SQLTABLES] == SQL_TRUE &&
fExists[SQL_API_SQLCOLUMNS] == SQL_TRUE &&
fExists[SQL_API_SQLSTATISTICS] == SQL_TRUE)
{
/* Continue with application */
}
SQLDisconnect(hdbc);
Funções relacionadas
| Para obter informações sobre | Consulte |
|---|---|
| Retornando a configuração de um atributo de conexão | Função SQLGetConnectAttr |
| Retornando informações sobre um driver ou fonte de dados | Função SQLGetInfo |
| Retornando a configuração de um atributo de instrução | Função SQLGetStmtAttr |