Função SQLGetFunctions

Conformidade
Versão Introduzida: Normas ODBC 1.0 Conformidade: ISO 92

Summary
O SQLGetFunctions devolve informação sobre se um driver suporta uma função ODBC específica. Esta função é implementada no Gestor de Drivers; Também pode ser implementado em drivers. Se um driver implementar SQLGetFunctions, o Gestor de Drivers chama a função no driver. Caso contrário, executa a própria função.

Syntax

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

Arguments

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

Para uma lista de valores de #define que identificam funções ODBC, consulte 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. Este array é tratado pelo Gestor 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. (Ver "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 for 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 estão não utilizados 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 identifica uma função ODBC não suportada pelo driver ou se não identifica uma função ODBC.

Os arrays devolvidos em *SupportedPtr utilizam indexação baseada em zero.

Devoluções

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR ou SQL_INVALID_HANDLE.

Diagnósticos

Quando o 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 seguinte lista os valores SQLSTATE comumente devolvidos pelo SQLGetFunctions e explica cada um no contexto desta função; a notação "(DM)" precede as descrições dos SQLSTATEs devolvidas pelo Gestor de Drivers. O código de retorno associado a cada valor SQLSTATE é SQL_ERROR, salvo indicação em contrário.

Comments

SQLGetFunctions devolve sempre que SQLGetFunctions, SQLDataSources e SQLDrivers são suportados. Faz isto porque estas funções são implementadas no Gestor de Drivers. O Gestor de Drivers irá mapear uma função ANSI para a função Unicode correspondente se a função Unicode existir e irá 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, consulte Níveis de Conformidade da Interface.

Segue-se uma lista de valores válidos para o FunctionId para funções que cumprem o nível de conformidade com a norma ISO 92:

Segue-se 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:

Segue-se uma lista de valores válidos para o FunctionId para funções que cumprem o nível de conformidade com os padrões ODBC.

[1] Ao trabalhar com um driver ODBC 2*.x*, o SQLBulkOperations só será devolvido como suportado se ambas as seguintes condições forem verdadeiras: o driver ODBC 2*.x* suporta SQLSetPos, e o tipo de informação SQL_POS_OPERATIONS devolve o bit SQL_POS_ADD como definido.

Segue-se uma lista de valores válidos para o FunctionId para funções introduzidas no ODBC 3.8 ou posteriores:

[2] O SQLCancelHandle será devolvido como suportado apenas se o driver suportar tanto o SQLCancel como o SQLCancelHandle. Se o SQLCancel for suportado mas o SQLCancelHandle não, a aplicação ainda pode chamar o SQLCancelHandle num handle de instrução, pois este será mapeado para SQLCancel.

SQL_FUNC_EXISTS Macro

A macro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) é usada para determinar o suporte de 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 devolve SQL_TRUE se a função for suportada, e SQL_FALSE caso contrário.

Exemplo de código

Os três exemplos seguintes mostram como uma aplicação utiliza SQLGetFunctions para determinar se um driver suporta SQLTables, SQLColumns e SQLStatistics. Se o driver não suportar estas funções, a aplicação desliga-se 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-lhe um array no qual SQLGetFunctions devolve informação 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-lhe um array de 100 elementos no qual SQLGetFunctions devolve informação 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
• Ficheiros de Cabeçalho ODBC