Condividi tramite


SQLGetFunctions Function

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

Riepilogo
SQLGetFunctions restituisce informazioni su se un driver supporta una funzione ODBC specifica. Questa funzione viene implementata in Gestione driver; può anche essere implementato nei driver. Se un driver implementa SQLGetFunctions, Gestione driver chiama la funzione nel driver. In caso contrario, esegue la funzione stessa.

Sintassi

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

Argomenti

ConnectionHandle
[Input] Handle di connessione.

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

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

SupportedPtr
[Output] Se FunctionId identifica una singola funzione ODBC, SupportedPtr punta a un singolo valore SQLUSMALLINT 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 una matrice SQLSMALLINT con un numero di elementi uguale a SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Questa matrice viene considerata da Gestione driver come bitmap a 4.000 bit che può essere usata per determinare se è supportata una funzione ODBC 3*.x* o precedente. La macro SQL_FUNC_EXISTS viene chiamata per determinare il supporto delle funzioni. (Vedere "Comments.") Un'applicazione ODBC 3*.x* può chiamare SQLGetFunctions con SQL_API_ODBC3_ALL_FUNCTIONS su un driver ODBC 3*.x* o ODBC 2*.x*.

Se FunctionId è SQL_API_ALL_FUNCTIONS, SupportedPtr punta a una matrice SQLUSMALLINT di 100 elementi. La matrice viene indicizzata da #define valori utilizzati da FunctionId per identificare ogni funzione ODBC. Alcuni elementi della matrice non vengono usati 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 non identifica una funzione ODBC.

Le matrici restituite in *SupportedPtr usano l'indicizzazione in base zero.

Resi

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR o SQL_INVALID_HANDLE.

Diagnostica

Quando SQLGetFunctions restituisce SQL_ERROR o SQL_SUCCESS_WITH_INFO, è possibile ottenere un valore SQLSTATE associato chiamando SQLGetDiagRec con handleTypedi SQL_HANDLE_DBC e handle di ConnectionHandle. La tabella seguente elenca i valori SQLSTATE comunemente restituiti da SQLGetFunctions e spiega ognuno di essi nel contesto di questa funzione. La notazione "(DM)" precede le descrizioni di SQLSTATEs restituite da Gestione driver. Il codice restituito associato a ogni valore SQLSTATE è SQL_ERROR, a meno che non sia specificato diversamente.

SQLSTATE Errore Descrizione
01000 Avviso generale Messaggio informativo specifico del driver. (La funzione restituisce SQL_SUCCESS_WITH_INFO.
08S01 Errore del collegamento di comunicazione Collegamento di comunicazione tra il driver e l'origine dati a cui è stato connesso il driver non è riuscito prima del completamento dell'elaborazione della funzione.
HY000 Errore generale: Si è verificato un errore per il quale non è stato specificato SQLSTATE e per il quale non è stato definito alcun SQLSTATE specifico dell'implementazione. Il messaggio di errore restituito da SQLGetDiagRec nel buffer *MessageText descrive l'errore e la relativa causa.
HY001 Errore di allocazione della memoria Il driver non è riuscito ad allocare memoria necessaria per supportare l'esecuzione o il completamento della funzione.
HY010 Errore della sequenza di funzioni (DM) SQLGetFunctions è stato chiamato prima di SQLConnect, SQLBrowseConnect o SQLDriverConnect.

(DM) SQLBrowseConnect è stato chiamato per ConnectionHandlee restituito SQL_NEED_DATA. Questa funzione è stata chiamata prima che SQLBrowseConnect restituisca SQL_SUCCESS_WITH_INFO o SQL_SUCCESS.

(DM) SQLExecute, SQLExecDirect o SQLMoreResults è stato chiamato per ConnectionHandle e restituito SQL_PARAM_DATA_AVAILABLE. Questa funzione è stata chiamata prima del recupero dei dati per tutti i parametri trasmessi.
HY013 Errore di gestione della memoria Impossibile elaborare la chiamata di funzione perché non è stato possibile accedere agli oggetti di memoria sottostanti, probabilmente a causa di condizioni di memoria insufficiente.
HY095 Tipo di funzione non compreso nell'intervallo (DM) È stato specificato un valore FunctionId non valido.
HY117 La connessione viene sospesa a causa dello stato sconosciuto della transazione. Sono consentite solo funzioni disconnesse e di sola lettura. (DM) Per altre informazioni sullo stato sospeso, vedere Funzione SQLEndTran.
HYT01 Il timeout della connessione è scaduto Periodo di timeout della connessione scaduto prima che l'origine dati rispondesse alla richiesta. Il periodo di timeout della connessione viene impostato tramite SQLSetConnectAttr, SQL_ATTR_CONNECTION_TIMEOUT.

Commenti

SQLGetFunctions restituisce sempre che sono supportati SQLGetFunctions, SQLDataSources e SQLDrivers . Ciò avviene perché queste funzioni vengono implementate in Gestione driver. Gestione driver eseguirà il mapping di una funzione ANSI alla funzione Unicode corrispondente, se esiste la funzione Unicode e eseguirà il mapping di una funzione Unicode alla funzione ANSI corrispondente, se esiste la funzione ANSI. Per informazioni su come le applicazioni usano SQLGetFunctions, vedere Livelli di conformità dell'interfaccia.

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

Valore FunctionId Valore 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

Di seguito è riportato un elenco di valori validi per FunctionId per le funzioni conformi al livello di conformità standard open group:

Valore FunctionId Valore FunctionId
SQL_API_SQLCOLUMNS SQL_API_SQLSTATISTICS
SQL_API_SQLSPECIALCOLUMNS SQL_API_SQLTABLES

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

Valore FunctionId Valore 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] Quando si utilizza un driver ODBC 2*.x*, SQLBulkOperations verrà restituito come supportato solo se sono soddisfatte entrambe le condizioni seguenti: il driver ODBC 2*.x* supporta SQLSetPos e il tipo di informazioni SQL_POS_OPERATIONS restituisce il bit SQL_POS_ADD impostato.

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

Valore FunctionId
SQL_API_SQLCANCELHANDLE [2]

[2] SQLCancelHandle verrà restituito come supportato solo se il driver supporta sia SQLCancel che SQLCancelHandle. Se SQLCancel è supportato ma SQLCancelHandle non è, l'applicazione può comunque chiamare SQLCancelHandle in un handle di istruzione, perché verrà eseguito il mapping a SQLCancel.

SQL_FUNC_EXISTS Macro

La macro SQL_FUNC_EXISTS(SupportedPtr, FunctionID) viene usata per determinare il supporto delle funzioni ODBC 3*.x* o 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 in caso contrario.

Nota

Quando si usa un driver ODBC 2*.x*, gestione driver ODBC 3*.x* restituirà SQL_TRUE per SQLAllocHandle e SQLFreeHandle perché SQLAllocHandle è mappato a SQLAllocEnv, SQLAllocConnect o SQLAllocStmt e perché SQLFreeHandle è mappato a SQLFreeEnv, SQLFreeConnect o SQLFreeStmt. SQLAllocHandle o SQLFreeHandle con un argomento HandleType di SQL_HANDLE_DESC non è tuttavia supportato, anche se SQL_TRUE viene restituito per le funzioni, perché non esiste alcuna funzione ODBC 2*.x* a cui eseguire il mapping in questo caso.

Esempio di codice

I tre esempi seguenti illustrano come un'applicazione usa SQLGetFunctions per determinare se un driver supporta tabelle SQLTable, 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 la passa a una matrice 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 (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);  

Il terzo esempio è un'applicazione ODBC 2.x chiama SQLGetFunctions e lo passa a una matrice 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);  
Per informazioni su Vedere
Restituzione dell'impostazione di un attributo di connessione Funzione SQLGetConnectAttr
Restituzione di informazioni su un driver o un'origine dati Funzione SQLGetInfo
Restituzione dell'impostazione di un attributo di istruzione Funzione SQLGetStmtAttr

Vedi anche

Riferimento API ODBC
File di intestazione ODBC