Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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.
| SQLSTATE | Error | Description |
|---|---|---|
| 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 veniva chiamato prima di SQLConnect, SQLBrowseConnect o SQLDriverConnect. (DM) SQLBrowseConnect veniva chiamato per il ConnectionHandle e restituiva SQL_NEED_DATA. Questa funzione veniva chiamata prima che SQLBrowseConnect restituisse SQL_SUCCESS_WITH_INFO o SQL_SUCCESS. (DM) SQLExecute, SQLExecDirect o SQLMoreResults veniva chiamato per il 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 fuori dalla portata | (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. |
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:
| 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 funzioni conformi al livello di conformità agli 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 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 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:
| Valore FunctionId |
|---|
| SQL_API_SQLCANCELHANDLE [2] |
[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.
Note
Quando si lavora con un driver ODBC 2*.x*, il Driver Manager ODBC 3*.x* restituirà SQL_TRUE per SQLAllocHandle e SQLFreeHandle perché SQLAllocHandle è mappato su SQLAllocEnv, SQLAllocConnect o SQLAllocStmt, e perché SQLFreeHandle è mappato in SQLFreeEnv, SQLFreeConnect o SQLFreeStmt. Tuttavia, SQLAllocHandle o SQLFreeHandle con un argomento HandleType di SQL_HANDLE_DESC non sono supportati, anche se SQL_TRUE viene restituito per le funzioni, perché in questo caso non esiste una funzione ODBC 2*.x* a cui mappare.
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
| Per informazioni su | Vedi |
|---|---|
| Restituzione dell'impostazione di un attributo di connessione | Funzione SQLGetConnectAttr |
| Restituire informazioni su un driver o una fonte di dati | Funzione SQLGetInfo |
| Restituzione dell'impostazione di un attributo di istruzione | Funzione SQLGetStmtAttr |