SQLGetFunctions 函式

發行項
08/21/2023

一致性
引進版本：ODBC 1.0 標準合規性：ISO 92

摘要
SQLGetFunctions 會傳回驅動程式是否支援特定 ODBC 函式的相關資訊。此函式會在驅動程式管理員中實作;它也可以在驅動程式中實作。如果驅動程式實作 SQLGetFunctions ，驅動程式管理員會在驅動程式中呼叫函式。否則，它會執行函式本身。

語法

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

引數

ConnectionHandle
[輸入] 連線控制代碼。

FunctionId
[輸入] 識別感興趣之 ODBC 函式的 #define 值; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS 。 ODBC 3*.x* 應用程式會使用SQL_API_ODBC3_ALL_FUNCTIONS 來判斷 ODBC 3*.x* 和舊版函式的支援。 ODBC 2*.x* 應用程式會使用SQL_API_ALL_FUNCTIONS 來判斷 ODBC 2*.x* 和舊版函式的支援。

如需識別 ODBC 函式的 #define 值清單 ，請參閱中的資料表。

SupportedPtr
[輸出]如果 FunctionId 識別單一 ODBC 函式， SupportedPtr 會指向驅動程式支援指定函式時SQL_TRUE的單一 SQLUSMALLINT 值，如果不支援，SQL_FALSE。

如果 FunctionId 是SQL_API_ODBC3_ALL_FUNCTIONS， SupportedPtr 會指向數個元素等於SQL_API_ODBC3_ALL_FUNCTIONS_SIZE的 SQLSMALLINT 陣列。驅動程式管理員會將此陣列視為 4，000 位位點陣圖，可用來判斷是否支援 ODBC 3*.x* 或更早的函式。呼叫 SQL_FUNC_EXISTS 宏來判斷函式支援。（請參閱「批註」。）ODBC 3*.x* 應用程式可以針對 ODBC 3*.x* 或 ODBC 2*.x* 驅動程式呼叫 具有SQL_API_ODBC3_ALL_FUNCTIONS的 SQLGetFunctions 。

如果 FunctionId 是SQL_API_ALL_FUNCTIONS， SupportedPtr 會指向 100 個元素的 SQLUSMALLINT 陣列。陣列是由 FunctionId 用來識別每個 ODBC 函式所使用的 #define 值編制索引;陣列的某些元素未使用，並保留供日後使用。如果元素識別驅動程式支援的 ODBC 2*.x* 或更早函式，則會SQL_TRUE專案。如果它識別驅動程式不支援的 ODBC 函式或未識別 ODBC 函式，則會SQL_FALSE。

* SupportedPtr 中傳回的 陣列會使用以零起始的索引。

傳回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

診斷

當 SQLGetFunctions 傳回SQL_ERROR或SQL_SUCCESS_WITH_INFO時，藉由呼叫具有 SQL_HANDLE_DBC HandleType 和 ConnectionHandle 的 HandleType 呼叫 SQLGetDiagRec ，即可取得相關聯的 SQLSTATE 值。下表列出 SQLGetFunctions 通常傳 回的 SQLSTATE 值，並說明此函式內容中的每個值;標記法「（DM）」在驅動程式管理員傳回的 SQLSTATE 描述之前。除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

SQLSTATE	錯誤	描述
01000	一般警告	驅動程式特定的資訊訊息。（函式會傳回SQL_SUCCESS_WITH_INFO。）
08S01	通訊連結失敗	驅動程式與驅動程式連線的資料來源之間的通訊連結在函式完成處理之前失敗。
HY000	一般錯誤	發生錯誤，其中沒有特定的 SQLSTATE，也沒有定義任何實作特定的 SQLSTATE。 MessageText 緩衝區中* SQLGetDiagRec 傳回的錯誤訊息描述錯誤及其原因。
HY001	記憶體配置錯誤	驅動程式無法配置支援執行或完成函式所需的記憶體。
HY010	函式順序錯誤	（DM）在 SQLConnect、 SQLBrowseConnect 或 SQLDriverConnect 之前呼叫 SQLGetFunctions 。（DM）已針對 ConnectionHandle 呼叫 SQLBrowseConnect ，並傳回SQL_NEED_DATA。此函式是在 SQLBrowseConnect 傳回SQL_SUCCESS_WITH_INFO或SQL_SUCCESS之前呼叫的。（DM）已針對 ConnectionHandle 呼叫 SQLExecute 、 SQLExecDirect 或 SQLMoreResults ，並傳回SQL_PARAM_DATA_AVAILABLE。在擷取所有資料流程參數的資料之前，會呼叫此函式。
HY013	記憶體管理錯誤	無法處理函式呼叫，因為基礎記憶體物件無法存取，可能是因為記憶體不足的情況。
HY095	超出範圍的函式類型	（DM）指定了無效的 FunctionId 值。
HY117	連線因為未知的交易狀態而暫停。只允許中斷連線和唯讀函式。	（DM）如需暫停狀態的詳細資訊，請參閱 SQLEndTran 函式。
HYT01	已超過連線逾時	在資料來源回應要求之前，連線逾時期限已過期。連線逾時期間是透過 SQLSetConnectAttr 來設定，SQL_ATTR_CONNECTION_TIMEOUT。

註解

SQLGetFunctions 一律會傳回 支援 SQLGetFunctions 、 SQLDataSources 和 SQLDrivers 。這樣做是因為這些函式會在驅動程式管理員中實作。如果 Unicode 函式存在，驅動程式管理員會將 ANSI 函式對應至對應的 Unicode 函式，如果 ANSI 函式存在，則會將 Unicode 函式對應至對應的 ANSI 函式。如需應用程式 如何使用 SQLGetFunctions 的詳細資訊，請參閱介面一致性層級。

以下是符合 ISO 92 標準合規性層級之函式的 FunctionId 有效值 清單：

FunctionId 值	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_SQLGETEN加值稅TR
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_SQLSETEN加值稅TR
SQL_API_SQLGETCURSORNAME	SQL_API_SQLSETSTMTATTR
SQL_API_SQLGETDATA

以下是符合 Open Group 標準合規性層級之函式的 FunctionId 有效值 清單：

FunctionId 值	FunctionId 值
SQL_API_SQLCOLUMNS	SQL_API_SQLSTATISTICS
SQL_API_SQLSPECIALCOLUMNS	SQL_API_SQLTABLES

以下是符合 ODBC 標準合規性層級之函式的 FunctionId 有效值 清單。

FunctionId 值	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] 使用 ODBC 2*.x* 驅動程式時，只有在下列兩項都成立時， 才會傳回 SQLBulkOperations ：ODBC 2*.x* 驅動程式支援 SQLSetPos ，而且資訊類型SQL_POS_OPERATIONS傳回SQL_POS_ADD位。

以下是 ODBC 3.8 或更新版本中引進之函式 FunctionId 的有效值 清單：

FunctionId 值
SQL_API_SQLCANCELHANDLE [2]

[2] 只有在驅動程式同時支援 SQLCancel 和 SQLCancelHandle 時，才會以支援的形式傳回 SQLCancelHandle 。如果支援 SQLCancel 但 SQLCancelHandle 不是，應用程式仍然可以在語句控制碼上呼叫 SQLCancelHandle ，因為它會對應至 SQLCancel 。

SQL_FUNC_EXISTS宏

SQL_FUNC_EXISTS（SupportedPtr ， FunctionID ）宏是用來判斷在呼叫 SQLGetFunctions 之後 ，使用 SQL_API_ODBC3_ALL_FUNCTIONS 的 FunctionId 引數來判斷 ODBC 3*.x* 或舊版函式 的支援。應用程式會呼叫 SQL_FUNC_EXISTS，並將 SupportedPtr 引數設定為 SQLGetFunctions 中傳遞的 SupportedPtr ，並將 FunctionID 引數設定為 函式的 #define 。 如果支援函式，SQL_FUNC_EXISTS會傳回SQL_TRUE，否則會傳回 SQL_FALSE。

注意

使用 ODBC 2*.x* 驅動程式時，ODBC 3*.x* 驅動程式管理員會傳回 SQLAllocHandle 和 SQLFreeHandle 的SQL_TRUE，因為 SQLAllocHandle 會對應至 SQLAllocEnv 、 SQLAllocConnect 或 SQLAllocStmt ，而且因為 SQLFreeHandle 對應至 SQLFreeEnv 、 SQLFreeConnect 或 SQLFreeStmt 。不支援具有 SQL_HANDLE_DESC HandleType 引數的 SQLAllocHandle 或 SQLFreeHandle ，不過即使函式傳回SQL_TRUE，因為在此情況下沒有 ODBC 2*.x* 函式可對應至。

程式碼範例

下列三個範例示範應用程式 如何使用 SQLGetFunctions 來判斷驅動程式是否支援 SQLTables 、 SQLColumns 和 SQLStatistics 。如果驅動程式不支援這些函式，應用程式會中斷與驅動程式的連接。第一個範例會針對每個函式呼叫 SQLGetFunctions 一次。

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

在第二個範例中，ODBC 3.x 應用程式會呼叫 SQLGetFunctions ，並傳遞一個陣列 ，其中 SQLGetFunctions 會傳回所有 ODBC 3.x 和舊版函式的相關資訊。

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

第三個範例是 ODBC 2.x 應用程式會呼叫 SQLGetFunctions ，並傳遞 100 個元素 的陣列，其中 SQLGetFunctions 會傳回所有 ODBC 2.x 和舊版函式的相關資訊。

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

如需下列資訊	請參閱
傳回連接屬性的設定	SQLGetConnectAttr 函式
傳回驅動程式或資料來源的相關資訊	SQLGetInfo 函式
傳回語句屬性的設定	SQLGetStmtAttr 函式

另請參閱

ODBC API 參考
 ODBC 標頭檔

共用方式為

SQLGetFunctions 函式

語法

引數

傳回

診斷

註解

SQL_FUNC_EXISTS宏

程式碼範例

另請參閱

意見反應

其他資源

共用方式為

SQLGetFunctions 函式

語法

引數

傳回

診斷

註解

SQL_FUNC_EXISTS宏

程式碼範例

相關函數

另請參閱

意見反應

其他資源