SQLGetFunctions-Funktion

  • Artikel

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

Weitere Informationen

ODBC-API-Referenz
ODBC-Headerdateien