SQLGetFunctions 函式

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

總結
SQLGetFunctions 回傳驅動程式是否支援特定 ODBC 函式的資訊。此功能實作於驅動程式管理器中;它也可以實作在驅動程式中。若驅動程式實作 SQLGetFunctions，驅動程式管理員會呼叫該函式。否則，它會執行該函式本身。

Syntax

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

論點

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

FunctionID
[輸入]一個 #define 值，用以識別感興趣的ODBC函數; SQL_API_ODBC3_ALL_FUNCTIONS orSQL_API_ALL_FUNCTIONS。 SQL_API_ODBC3_ALL_FUNCTIONS 被 ODBC 3*.x* 應用程式用來判斷對 ODBC 3*.x* 及更早期功能的支援。 SQL_API_ALL_FUNCTIONS 被 ODBC 2*.x* 應用程式用來判斷對 ODBC 2*.x* 及更早功能的支援。

關於識別 ODBC 函數的 #define 值清單，請參閱「註解」中的表格。

支援玩家
[輸出]如果 FunctionID 識別出單一 ODBC 函式， SupportedPtr 會指向一個 SQLUSMALLINT 值，若該函式被驅動程式支援，則SQL_TRUE，若不支援則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* 應用程式可以呼叫帶有 SQL_API_ODBC3_ALL_FUNCTIONS 的 SQLGetFunctions ，針對 ODBC 3*.x* 或 ODBC 2*.x* 驅動程式。

若 FunctionID 為 SQL_API_ALL_FUNCTIONS，SupportedPtr 會指向一個包含 100 個元素的 SQLUSMALLINT 陣列。陣列由 FunctionID 用來識別每個 ODBC 函式的 #define 值來索引;陣列中有些元素未被使用，保留以供未來使用。若該元素識別驅動程式支援的 ODBC 2*.x* 或更早函式，則該元素被SQL_TRUE。若識別驅動程式不支援的 ODBC 函式，或無法識別 ODBC 函式，則SQL_FALSE。

*SupportedPtr 中回傳的陣列使用零為基礎的索引。

Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

Diagnostics

當 SQLGetFunctions 回傳 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 時，可以透過呼叫 SQLGetDiagRec 並設定 HandleType 為 SQL_HANDLE_DBC 和 HandleHandle 的 Handle，取得相關的 SQLSTATE 值。下表列出 SQLGetFunctions 常回傳的 SQLSTATE 值，並在此函式的情境中解釋每個值;「（DM）」符號會置於驅動程式管理器回傳的 SQLSTATE 描述前。除非另有說明，否則與每個 SQLSTATE 值相關聯的傳回碼會SQL_ERROR。

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

SQLGetFunctions 總是回傳支援 SQLGetFunctions、 SQLDataSources 和 SQLDrivers 。之所以如此，是因為這些功能是在驅動程式管理器中實作的。驅動程式管理器會將 ANSI 函式對應到對應的 Unicode 函式（若存在 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_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

以下是符合開放群組標準合規層級的函式中， 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）巨集用於判斷在以 FunctionID 參數 SQL_API_ODBC3_ALL_FUNCTIONS 呼叫 SQLGetFunctions 後，是否支援 ODBC 3*.x* 或更早的函式。 SQL_FUNC_EXISTS應用程式呼叫時，SupportedPtr 參數設為 SQLGetFunctions 中傳遞的 SupportedPtr，FunctionID 參數則設定為函式的 #define。 SQL_FUNC_EXISTS 回傳 SQL_TRUE 若函式被支援，否則SQL_FALSE。

Note

當使用 ODBC 2*.x* 驅動程式時，ODBC 3*.x* 驅動程式管理器會回傳 SQLAllocHandle 和 SQLFreeHandle 的 SQL_TRUE，因為 SQLAllocHandle 對應至 SQLAllocEnv、 SQLAllocConnect 或 SQLAllocStmt，且 SQLFreeHandle 對應至 SQLFreeEnv、 SQLFreeConnect 或 SQLFreeStmt。然而，即使函式回傳 SQL_TRUE，也未支援帶有 HandleType 參數 SQL_HANDLE_DESC 的 SQLAllocHandle 或 SQLFreeHandle，因為此時沒有 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 函式

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-08-24