SQLGetFunctions 函式
一致性
引進版本：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 (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);
第三個範例是 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 函式 |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應