共用方式為


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 函式

另請參閱

ODBC API 參考
ODBC 標頭檔