Função SQLGetFunctions

Conformidade
Versão introduzida: ODBC 1.0 Conformidade com os padrões: ISO 92

Summary
O SQLGetFunctions retorna informações sobre se um driver suporta uma função ODBC específica. Essa função é implementada no Gerenciador de Drivers; Também pode ser implementado em drivers. Se um driver implementa SQLGetFunctions, o Gerenciador de Drivers chama a função no driver. Caso contrário, ela executa a função em si.

Sintaxe

  
SQLRETURN SQLGetFunctions(  
     SQLHDBC           ConnectionHandle,  
     SQLUSMALLINT      FunctionId,  
     SQLUSMALLINT *    SupportedPtr);  

Argumentos

Identificador de conexão
[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 uma aplicação ODBC 3*.x* para determinar o suporte a ODBC 3*.x* e funções anteriores. SQL_API_ALL_FUNCTIONS é usado por uma aplicação ODBC 2*.x* para determinar o suporte a funções ODBC 2*.x* e anteriores.

Para uma lista de valores de #define que identificam funções ODBC, veja as tabelas em "Comentários."

SuportadoPtr
[Saída] Se o FunctionId identificar uma única função ODBC, o SupportedPtr aponta para um único valor SQLUSMALLINT que é SQL_TRUE se a função especificada for suportada pelo driver, e SQL_FALSE se não for suportada.

Se o FunctionId for SQL_API_ODBC3_ALL_FUNCTIONS, o SupportedPtr aponta para um array SQLSMALLINT com um número de elementos igual a SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Esse array é tratado pelo Gerenciador de Drivers como um bitmap de 4.000 bits que pode ser usado para determinar se uma função ODBC 3*.x* ou anterior é suportada. A macro SQL_FUNC_EXISTS é chamada para determinar o suporte à função. (Veja "Comentários.") Uma aplicação ODBC 3*.x* pode chamar SQLGetFunctions com SQL_API_ODBC3_ALL_FUNCTIONS contra um driver ODBC 3*.x* ou ODBC 2*.x*.

Se o FunctionId estiver SQL_API_ALL_FUNCTIONS, o SupportedPtr aponta para um array SQLUSMALLINT de 100 elementos. O array é indexado por #define valores usados pelo FunctionId para identificar cada função ODBC; Alguns elementos do array ficam inutilizados e reservados para uso futuro. Um elemento é SQL_TRUE se identificar uma função ODBC 2*.x* ou anterior suportada pelo driver. É SQL_FALSE se identificar uma função ODBC não suportada pelo driver ou não identificar uma função ODBC.

Os arrays retornados em *SupportedPtr usam indexação baseada em zero.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnostics

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 Handle de ConnectionHandle. A tabela a seguir lista os valores SQLSTATE comumente retornados pelo SQLGetFunctions e explica cada um no contexto dessa função; a notação "(DM)" precede as descrições dos SQLSTATEs retornadas pelo Gerenciador de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, a menos que indicado de outra forma.

Comments

SQLGetFunctions sempre retorna que SQLGetFunctions, SQLDataSources e SQLDrivers são suportados. Ele faz isso porque essas funções são implementadas no Gerenciador de Drivers. O Gerenciador de Drivers 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 informações sobre como as aplicações utilizam SQLGetFunctions, veja Níveis de Conformidade da Interface.

A seguir está uma lista de valores válidos para o FunctionId para funções que cumprem o nível de conformidade com as normas ISO 92:

A seguir está uma lista de valores válidos para o FunctionId para funções que cumprem o nível de conformidade com os padrões do Open Group:

A seguir está uma lista de valores válidos para o FunctionId para funções que estão em conformidade com o nível de conformidade com os padrões ODBC.

[1] Ao trabalhar com um driver ODBC 2*.x*, SQLBulkOperations será retornado como suportado somente se ambos os seguintes pontos forem verdadeiros: o driver ODBC 2*.x* suporta SQLSetPos, e o tipo de informação SQL_POS_OPERATIONS retorna o bit SQL_POS_ADD como definido.

A seguir está uma lista de valores válidos para o FunctionId para funções introduzidas no ODBC 3.8 ou posterior:

[2] SQLCancelHandle será retornado como suportado somente se o driver suportar tanto SQLCancel quanto SQLCancelHandle. Se o SQLCancel for suportado, mas o SQLCancelHandle não, a aplicação ainda pode chamar o SQLCancelHandle em um handle 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 a ODBC 3*.x* ou funções anteriores após o SQLGetFunctions ter sido chamado com um argumento FunctionId de SQL_API_ODBC3_ALL_FUNCTIONS. A aplicação chama SQL_FUNC_EXISTS com o argumento SupportedPtr definido para o SupportedPtr passado em SQLGetFunctions, e com o argumento FunctionID definido para o #define da função. SQL_FUNC_EXISTS retorna SQL_TRUE se a função for suportada, e SQL_FALSE contrário.

Exemplo de código

Os três exemplos a seguir mostram como uma aplicação usa SQLGetFunctions para determinar se um driver suporta SQLTables, SQLColumns e SQLStatistics. Se o driver não suportar essas funções, o aplicativo se desconecta 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, uma aplicação ODBC 3.x chama SQLGetFunctions e passa a ela um array no 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 é uma aplicação ODBC 2.x chamada SQLGetFunctions e passa a ele um array de 100 elementos no qual 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

Conteúdo relacionado

• Referência da API ODBC
• Arquivos de cabeçalho ODBC