La funzione SQLGetFunctions

Conformità
Versione introdotta: Conformità agli standard ODBC 1.0: ISO 92

Sommario
SQLGetFunctions restituisce informazioni sul fatto che un driver supporti una specifica funzione ODBC. Questa funzione è implementata nel Driver Manager; può essere implementato anche nei driver. Se un driver implementa SQLGetFunctions, il Driver Manager chiama la funzione nel driver. Altrimenti, esegue la funzione stessa.

Sintassi

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

Arguments

ConnectionHandle
[Input] Identificatore di connessione.

FunctionId
[Input] Un valore #define che identifica la funzione ODBC di interesse; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS. SQL_API_ODBC3_ALL_FUNCTIONS viene utilizzato da un'applicazione ODBC 3*.x* per determinare il supporto di ODBC 3*.x* e funzioni precedenti. SQL_API_ALL_FUNCTIONS viene utilizzato da un'applicazione ODBC 2*.x* per determinare il supporto di ODBC 2*.x* e funzioni precedenti.

Per un elenco dei valori di #define che identificano le funzioni ODBC, consulta le tabelle in "Commenti."

SupportedPtr
[Output] Se FunctionId identifica una singola funzione ODBC, SupportedPtr punta a un singolo valore SQLUSMALLINT che è SQL_TRUE se la funzione specificata è supportata dal driver, e SQL_FALSE se non è supportata.

Se FunctionId è SQL_API_ODBC3_ALL_FUNCTIONS, SupportedPtr punta a un array SQLSMALLINT con un numero di elementi pari a SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Questo array è trattato dal Driver Manager come una bitmap da 4.000 bit che può essere utilizzata per determinare se una funzione ODBC 3*.x* o precedente è supportata. La macro SQL_FUNC_EXISTS viene chiamata per determinare il supporto delle funzioni. (Vedi "Commenti.") Un'applicazione ODBC 3*.x* può chiamare SQLGetFunctions con SQL_API_ODBC3_ALL_FUNCTIONS contro un driver ODBC 3*.x* o ODBC 2*.x*.

Se FunctionId è SQL_API_ALL_FUNCTIONS, SupportedPtr punta a un array SQLUSMALLINT di 100 elementi. L'array è indicizzato da #define valori utilizzati da FunctionId per identificare ogni funzione ODBC; alcuni elementi dell'array sono inutilizzati e riservati per un uso futuro. Un elemento è SQL_TRUE se identifica una funzione ODBC 2*.x* o precedente supportata dal driver. È SQL_FALSE se identifica una funzione ODBC non supportata dal driver o se non identifica una funzione ODBC.

Gli array restituiti in *SupportedPtr utilizzano indicizzazione basata su zero.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLGetFunctions restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, un valore SQLSTATE associato può essere ottenuto chiamando SQLGetDiagRec con un HandleType di SQL_HANDLE_DBC e un Handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLGetFunctions e spiega ciascuno nel contesto di questa funzione; la notazione "(DM)" precede le descrizioni degli stati SQL restituite dal Driver Manager. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

Comments

SQLGetFunctions restituisce sempre che SQLGetFunctions, SQLDataSources e SQLDrivers sono supportati. Lo fa perché queste funzioni sono implementate nel Driver Manager. Il Driver Manager mapperà una funzione ANSI alla corrispondente funzione Unicode se la funzione Unicode esiste e mapperà una funzione Unicode alla corrispondente funzione ANSI se la funzione ANSI esiste. Per informazioni su come le applicazioni utilizzano SQLGetFunctions, vedi Livelli di conformità dell'interfaccia.

Di seguito è riportato un elenco di valori validi per FunctionId per funzioni che rispettano il livello di conformità agli standard ISO 92:

Di seguito è riportato un elenco di valori validi per FunctionId per funzioni conformi al livello di conformità agli standard Open Group:

Di seguito è riportato un elenco di valori validi per FunctionId per funzioni conformi al livello di conformità agli standard ODBC.

[1] Quando si lavora con un driver ODBC 2*.x*, SQLBulkOperations verrà restituito come supportato solo se entrambe le seguenti condizioni sono vere: il driver ODBC 2*.x* supporta SQLSetPos, e il tipo di informazione SQL_POS_OPERATIONS restituisce il bit SQL_POS_ADD come impostato.

Di seguito è riportato un elenco di valori validi per FunctionId per funzioni introdotte in ODBC 3.8 o successive:

[2] SQLCancelHandle sarà restituito come supportato solo se il driver supporta sia SQLCancel che SQLCancelHandle. Se SQLCancel è supportato ma SQLCancelHandle no, l'applicazione può comunque chiamare SQLCancelHandle su un'handle di un'istruzione, perché sarà mappata su SQLCancel.

SQL_FUNC_EXISTS Macro

La macro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) viene utilizzata per determinare il supporto di ODBC 3*.x* o funzioni precedenti dopo che SQLGetFunctions è stato chiamato con un argomento FunctionId di SQL_API_ODBC3_ALL_FUNCTIONS. L'applicazione chiama SQL_FUNC_EXISTS con l'argomento SupportedPtr impostato su SupportedPtr passato in SQLGetFunctions, e con l'argomento FunctionID impostato sul #define per la funzione. SQL_FUNC_EXISTS restituisce SQL_TRUE se la funzione è supportata, e SQL_FALSE altrimenti.

Esempio di codice

I seguenti tre esempi mostrano come un'applicazione utilizza SQLGetFunctions per determinare se un driver supporta SQLTables, SQLColumns e SQLStatistics. Se il driver non supporta queste funzioni, l'applicazione si disconnette dal driver. Il primo esempio chiama SQLGetFunctions una volta per ogni funzione.

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

Nel secondo esempio, un'applicazione ODBC 3.x chiama SQLGetFunctions e le passa un array in cui SQLGetFunctions restituisce informazioni su tutte le funzioni ODBC 3.x e precedenti.

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

Il terzo esempio è un'applicazione ODBC 2.x che chiama SQLGetFunctions e le passa un array di 100 elementi in cui SQLGetFunctions restituisce informazioni su tutte le funzioni ODBC 2.x e precedenti.

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

Funzioni correlate

Contenuti correlati

• Riferimento API ODBC
• File di intestazione ODBC