SQLGetFunctions-Funktion

Konformität
Version eingeführt: ODBC 1.0 Standards Compliance: ISO 92

Summary
SQLGetFunctions liefert Informationen darüber, ob ein Treiber eine bestimmte ODBC-Funktion unterstützt. Diese Funktion ist im Driver Manager implementiert; Sie kann auch in Treibern implementiert werden. Wenn ein Treiber SQLGetFunctions implementiert, ruft der Treibermanager die Funktion im Treiber auf. Andernfalls führt er die Funktion selbst aus.

Syntax

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

Argumente

ConnectionHandle
[Eingabe] Verbindungshandle.

FunctionId
[Eingabe] Ein #define Wert, der die wichtige 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 bestimmen. 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 bestimmen.

Eine Liste #define Werte, die ODBC-Funktionen identifizieren, finden Sie in den Tabellen unter "Kommentare".

SupportedPtr
[Ausgabe] Wenn FunctionId eine einzelne ODBC-Funktion identifiziert, zeigt 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, zeigt SupportedPtr auf ein SQLSMALLINT-Array mit einer Anzahl von Elementen gleich SQL_API_ODBC3_ALL_FUNCTIONS_SIZE. Dieses Array wird vom Driver Manager als 4.000-Bitmap behandelt, mit der bestimmt werden kann, ob eine ODBC 3*.x* oder frühere Funktion unterstützt wird. Das SQL_FUNC_EXISTS Makro wird aufgerufen, um die Funktionsunterstützung zu bestimmen. (Siehe "Kommentare.") Eine ODBC 3*.x*-Anwendung kann SQLGetFunctions mit SQL_API_ODBC3_ALL_FUNCTIONS gegen einen ODBC 3*.x* oder ODBC 2*.x*-Treiber aufrufen.

Wenn FunctionId SQL_API_ALL_FUNCTIONS ist, weist SupportedPtr auf ein SQLUSMALLINT-Array von 100 Elementen hin. Das Array wird durch #define Werte indiziert, die von FunctionId zur Identifikation jeder ODBC-Funktion verwendet werden; Einige Elemente des Arrays sind ungenutzt und für die zukünftige Nutzung reserviert. Ein Element ist SQL_TRUE, wenn es eine ODBC 2*.x* oder frühere Funktion identifiziert, die vom Treiber unterstützt wird. Es ist SQL_FALSE, ob sie eine ODBC-Funktion identifiziert, die vom Treiber nicht unterstützt wird, oder keine ODBC-Funktion identifiziert.

Die in *SupportedPtr zurückgegebenen Arrays verwenden nullbasierte Indexierung.

Rücklieferungen

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR oder SQL_INVALID_HANDLE.

Diagnostics

Wenn SQLGetFunctions SQL_ERROR oder SQL_SUCCESS_WITH_INFO zurückgibt, kann ein zugehöriger SQLSTATE-Wert erhalten werden, indem SQLGetDiagRec mit einem HandleType von SQL_HANDLE_DBC und einem Handle von ConnectionHandle aufgerufen wird. Die folgende Tabelle listet die SQLSTATE-Werte auf, die häufig von SQLGetFunctions zurückgegeben werden, und erklärt jeden einzelnen im Kontext dieser Funktion; die Notation "(DM)" geht den vom Treibermanager zurückgegebenen SQLSTATE-Beschreibungen voraus. Der rückgabecode, der jedem SQLSTATE-Wert zugeordnet ist, ist SQL_ERROR, sofern nicht anders angegeben.

Kommentare

SQLGetFunctions gibt immer an, dass SQLGetFunctions, SQLDataSources und SQLDrivers unterstützt werden. Dies geschieht, weil diese Funktionen im Driver Manager implementiert sind. Der Treibermanager bildet eine ANSI-Funktion auf die entsprechende Unicode-Funktion ab, falls die Unicode-Funktion existiert, und bildet eine Unicode-Funktion auf die entsprechende ANSI-Funktion ab, wenn die ANSI-Funktion existiert. Informationen darüber, wie Anwendungen SQLGetFunctions verwenden, finden Sie unter Interface Conformance Levels.

Im Folgenden finden Sie eine Liste gültiger Werte für FunctionId für Funktionen, die dem ISO-92-Standard-Compliance-Level entsprechen:

Im Folgenden findet sich eine Liste gültiger Werte für FunctionId für Funktionen, die dem Open Group-Standard-Compliance-Level entsprechen:

Im Folgenden findet sich eine Liste gültiger Werte für FunctionId für Funktionen, die dem ODBC-Standard-Compliance-Level entsprechen.

[1] Bei der Arbeit mit einem ODBC 2*.x*-Treiber wird SQLBulkOperations nur dann als unterstützt zurückgegeben, wenn beide Folgen zutreffen: 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 eine Liste gültiger Werte für FunctionId für Funktionen, die in ODBC 3.8 oder später eingeführt wurden:

[2] SQLCancelHandle wird nur dann 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 weiterhin SQLCancelHandle auf einem Anweisungshandle aufrufen, da dieser auf SQLCancel abgebildet 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 einem FunctionId-Argument von SQL_API_ODBC3_ALL_FUNCTIONS aufgerufen wurde. Die Anwendung ruft SQL_FUNC_EXISTS auf, wobei das Supported Ptr-Argument auf das in SQLGetFunctions übergegebene SupportedPtr gesetzt ist und das Argumente FunctionID auf das #define der Funktion gesetzt ist. SQL_FUNC_EXISTS gibt SQL_TRUE zurück, wenn die Funktion unterstützt wird, und SQL_FALSE anderweitig.

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, trennt sich die Anwendung vom Treiber. Das erste Beispiel ruft SQLGetFunctions einmal für jede Funktion auf.

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 über alle 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 (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);  

Das dritte Beispiel ist eine ODBC 2.x-Anwendung, die SQLGetFunctions aufruft und ihr ein Array von 100 Elementen übergibt, in denen SQLGetFunctions Informationen über alle 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

Verwandte Inhalte

• ODBC API-Referenz
• ODBC-Headerdateien