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