SQLGetFunctions-Funktion
Konformität
Version eingeführt: ODBC 1.0-Normenkonformität: ISO 92
Zusammenfassung
SQLGetFunctions gibt Informationen darüber zurück, ob ein Treiber eine bestimmte ODBC-Funktion unterstützt. Diese Funktion wird im Treiber-Manager implementiert. Es kann auch in Treibern implementiert werden. Wenn ein Treiber SQLGetFunctions implementiert, ruft der Treiber-Manager die Funktion im Treiber auf. Andernfalls wird die Funktion selbst ausgeführt.
Syntax
SQLRETURN SQLGetFunctions(
SQLHDBC ConnectionHandle,
SQLUSMALLINT FunctionId,
SQLUSMALLINT * SupportedPtr);
Argumente
ConnectionHandle
[Eingabe] Verbindungshandle.
Functionid
[Eingabe] Ein #define-Wert , der die interessante ODBC-Funktion identifiziert; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS. SQL_API_ODBC3_ALL_FUNCTIONS wird von einer ODBC 3*.x*-Anwendung verwendet, um die Unterstützung von ODBC 3*.x* und früheren Funktionen zu ermitteln. SQL_API_ALL_FUNCTIONS wird von einer ODBC 2*.x*-Anwendung verwendet, um die Unterstützung von ODBC 2*.x* und früheren Funktionen zu ermitteln.
Eine Liste mit #define Werten, die ODBC-Funktionen identifizieren, finden Sie in den Tabellen in "Kommentare".
SupportedPtr
[Ausgabe] Wenn FunctionId eine einzelne ODBC-Funktion identifiziert, verweist SupportedPtr auf einen einzelnen SQLUSMALLINT-Wert, der SQL_TRUE ist, wenn die angegebene Funktion vom Treiber unterstützt wird, und SQL_FALSE, wenn sie nicht unterstützt wird.
Wenn FunctionId SQL_API_ODBC3_ALL_FUNCTIONS ist, verweist SupportedPtr auf ein SQLSMALLINT-Array mit einer Anzahl von Elementen, die SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Dieses Array wird vom Treiber-Manager als 4.000-Bit-Bitmap behandelt, die verwendet werden kann, um zu bestimmen, ob eine ODBC 3*.x*-Funktion oder eine frühere Funktion unterstützt wird. Das SQL_FUNC_EXISTS Makros wird aufgerufen, um die Funktionsunterstützung zu bestimmen. (Siehe "Kommentare".) Eine ODBC 3*.x*-Anwendung kann SQLGetFunctions mit SQL_API_ODBC3_ALL_FUNCTIONS für einen ODBC 3*.x*- oder ODBC 2*.x*-Treiber aufrufen.
Wenn FunctionId SQL_API_ALL_FUNCTIONS ist, verweist SupportedPtr auf ein SQLUSMALLINT-Array mit 100 Elementen. Das Array wird von #define Werten indiziert, die von FunctionId verwendet werden, um jede ODBC-Funktion zu identifizieren. einige Elemente des Arrays sind nicht verwendet und für die zukünftige Verwendung reserviert. Ein Element wird SQL_TRUE, wenn es eine ODBC 2*.x* oder frühere Funktion identifiziert, die vom Treiber unterstützt wird. Es ist SQL_FALSE, wenn eine ODBC-Funktion identifiziert wird, die vom Treiber nicht unterstützt wird oder keine ODBC-Funktion identifiziert wird.
Die in *SupportedPtr zurückgegebenen Arrays verwenden nullbasierte Indizierung.
Gibt zurück
SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.
Diagnose
Wenn SQLGetFunctions SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugeordneter SQLSTATE-Wert abgerufen werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DBC und einem Handle of ConnectionHandle aufgerufen wird. In der folgenden Tabelle sind die SQLSTATE-Werte aufgeführt, die häufig von SQLGetFunctions zurückgegeben werden, und die einzelnen Werte werden im Kontext dieser Funktion erläutert. die Notation "(DM)" geht den Beschreibungen von SQLSTATEs voran, die vom Treiber-Manager zurückgegeben werden. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.
| SQLSTATE | Fehler | BESCHREIBUNG |
|---|---|---|
| 01000 | Allgemeine Warnung | Treiberspezifische Informationsmeldung. (Die Funktion gibt SQL_SUCCESS_WITH_INFO zurück.) |
| 08S01 | Kommunikationslinkfehler | Die Kommunikationsverbindung zwischen dem Treiber und der Datenquelle, mit der der Treiber verbunden war, ist fehlgeschlagen, bevor die Verarbeitung der Funktion abgeschlossen wurde. |
| HY000 | Allgemeiner Fehler | Es ist ein Fehler aufgetreten, für den kein spezifischer SQLSTATE-Wert vorhanden war und für den kein implementierungsspezifischer SQLSTATE-Wert definiert wurde. Die von SQLGetDiagRec im *MessageText-Puffer zurückgegebene Fehlermeldung beschreibt den Fehler und seine Ursache. |
| HY001 | Fehler bei der Speicherbelegung | Der Treiber konnte keinen Arbeitsspeicher zuordnen, der für die Unterstützung der Ausführung oder Vervollständigung der Funktion erforderlich ist. |
| HY010 | Funktionssequenzfehler | (DM) SQLGetFunctions wurde vor SQLConnect, SQLBrowseConnect oder SQLDriverConnect aufgerufen. (DM) SQLBrowseConnect wurde für ConnectionHandle aufgerufen und SQL_NEED_DATA zurückgegeben. Diese Funktion wurde aufgerufen, bevor SQLBrowseConnect SQL_SUCCESS_WITH_INFO oder SQL_SUCCESS zurückgegeben hat. (DM) SQLExecute, SQLExecDirect oder SQLMoreResults wurde für ConnectionHandle aufgerufen und SQL_PARAM_DATA_AVAILABLE zurückgegeben. Diese Funktion wurde aufgerufen, bevor Daten für alle gestreamten Parameter abgerufen wurden. |
| HY013 | Fehler bei der Speicherverwaltung | Der Funktionsaufruf konnte nicht verarbeitet werden, da auf die zugrunde liegenden Speicherobjekte nicht zugegriffen werden konnte, möglicherweise aufgrund von niedrigen Speicherbedingungen. |
| HY095 | Funktionstyp außerhalb des Bereichs | (DM) Ein ungültiger FunctionId-Wert wurde angegeben. |
| HY117 | Die Verbindung wird aufgrund eines unbekannten Transaktionsstatus angehalten. Nur Trennen und schreibgeschützte Funktionen sind zulässig. | (DM) Weitere Informationen zum Angehaltenen Zustand finden Sie unter SQLEndTran-Funktion. |
| HYT01 | Verbindungstimeout abgelaufen | Der Zeitraum für das Verbindungstimeout ist abgelaufen, bevor die Datenquelle auf die Anforderung reagiert hat. Der Zeitraum für das Verbindungstimeout wird über SQLSetConnectAttr festgelegt, SQL_ATTR_CONNECTION_TIMEOUT. |
Kommentare
SQLGetFunctions gibt immer zurück, dass SQLGetFunctions, SQLDataSources und SQLDrivers unterstützt werden. Dies geschieht, da diese Funktionen im Treiber-Manager implementiert sind. Der Treiber-Manager zuordnen eine ANSI-Funktion der entsprechenden Unicode-Funktion, wenn die Unicode-Funktion vorhanden ist, und zuordnen eine Unicode-Funktion der entsprechenden ANSI-Funktion, wenn die ANSI-Funktion vorhanden ist. Informationen dazu, wie Anwendungen SQLGetFunctions verwenden, finden Sie unter Schnittstellenkonformanzstufen.
Im Folgenden ist eine Liste der gültigen Werte für FunctionId für Funktionen aufgeführt, die der Iso 92-Standardkonformitätsstufe entsprechen:
| FunctionId-Wert | FunctionId-Wert |
|---|---|
| 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 |
Im Folgenden ist eine Liste der gültigen Werte für FunctionId für Funktionen aufgeführt, die der Open Group-Standardkompatibilitätsebene entsprechen:
| FunctionId-Wert | FunctionId-Wert |
|---|---|
| SQL_API_SQLCOLUMNS | SQL_API_SQLSTATISTICS |
| SQL_API_SQLSPECIALCOLUMNS | SQL_API_SQLTABLES |
Im Folgenden finden Sie eine Liste der gültigen Werte für FunctionId für Funktionen, die der ODBC-Standardkonformitätsebene entsprechen.
| FunctionId-Wert | FunctionId-Wert |
|---|---|
| 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] Wenn Sie mit einem ODBC 2*.x*-Treiber arbeiten, wird SQLBulkOperations nur dann als unterstützt zurückgegeben, wenn beides zutrifft: Der ODBC 2*.x*-Treiber unterstützt SQLSetPos, und der Informationstyp SQL_POS_OPERATIONS gibt das SQL_POS_ADD Bit wie festgelegt zurück.
Im Folgenden finden Sie eine Liste der gültigen Werte für FunctionId für Funktionen, die in ODBC 3.8 oder höher eingeführt wurden:
| FunctionId-Wert |
|---|
| SQL_API_SQLCANCELHANDLE [2] |
[2] SQLCancelHandle wird nur als unterstützt zurückgegeben, wenn der Treiber sowohl SQLCancel als auch SQLCancelHandle unterstützt. Wenn SQLCancel unterstützt wird, SQLCancelHandle jedoch nicht, kann die Anwendung sqlCancelHandle weiterhin für ein Anweisungshandle aufrufen, da es SQLCancel zugeordnet wird.
SQL_FUNC_EXISTS-Makro
Das Makro SQL_FUNC_EXISTS (SupportedPtr, FunctionID) wird verwendet, um die Unterstützung von ODBC 3*.x* oder früheren Funktionen zu bestimmen, nachdem SQLGetFunctions mit dem FunctionId-Argument SQL_API_ODBC3_ALL_FUNCTIONS aufgerufen wurde. Die Anwendung ruft SQL_FUNC_EXISTS auf, wobei das SupportedPtr-Argument auf den in SQLGetFunctions übergebenenSupportedPtr festgelegt ist und das Argument FunctionID auf den #define für die Funktion festgelegt ist. SQL_FUNC_EXISTS gibt SQL_TRUE zurück, wenn die Funktion unterstützt wird, und SQL_FALSE andernfalls.
Hinweis
Wenn Sie mit einem ODBC 2*.x*-Treiber arbeiten, gibt der ODBC 3*.x*-Treiber-Manager SQL_TRUE für SQLAllocHandle und SQLFreeHandle zurück, da SQLAllocHandleSQLAllocEnv, SQLAllocConnect oder SQLAllocStmt zugeordnet ist und SQLFreeHandleSQLFreeEnv, SQLFreeConnect oder SQLFreeStmt zugeordnet ist. SQLAllocHandle oder SQLFreeHandle mit dem HandleType-Argument SQL_HANDLE_DESC wird jedoch nicht unterstützt, obwohl SQL_TRUE für die Funktionen zurückgegeben wird, da es in diesem Fall keine ODBC 2*.x*-Funktion gibt, der zugeordnet werden kann.
Codebeispiel
Die folgenden drei Beispiele zeigen, wie eine Anwendung SQLGetFunctions verwendet, um zu bestimmen, ob ein Treiber SQLTables, SQLColumns und SQLStatistics unterstützt. Wenn der Treiber diese Funktionen nicht unterstützt, wird die Verbindung zwischen der Anwendung und dem Treiber getrennt. Im ersten Beispiel wird SQLGetFunctions einmal für jede Funktion aufgerufen.
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);
Im zweiten Beispiel ruft eine ODBC 3.x-Anwendung SQLGetFunctions auf und übergibt ihr ein Array, in dem SQLGetFunctions Informationen zu allen ODBC 3.x- und früheren Funktionen zurückgibt.
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);
Das dritte Beispiel ist eine ODBC 2.x-Anwendung, die SQLGetFunctions aufruft und ein Array von 100 Elementen übergibt, in dem SQLGetFunctions Informationen zu allen ODBC 2.x- und früheren Funktionen zurückgibt.
#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);
Verwandte Funktionen
| Informationen über | Finden Sie unter |
|---|---|
| Zurückgeben der Einstellung eines Verbindungsattributes | SQLGetConnectAttr-Funktion |
| Zurückgeben von Informationen zu einem Treiber oder einer Datenquelle | SQLGetInfo-Funktion |
| Zurückgeben der Einstellung eines Anweisungsattributs | SQLGetStmtAttr-Funktion |