Compartilhar via


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 (reccode == 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);  
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

Consulte Também

Referência de API do ODBC
Arquivos de cabeçalho ODBC