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.

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:

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:

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.

[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:

[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.

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);  

Funções relacionadas

Consulte Também

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