SQLGetFunctions 函数

一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92

总结
SQLGetFunctions 返回驱动程序是否支持特定 ODBC 函数的信息。该功能在驱动程序管理器中实现;它也可以在驱动程序中实现。如果驱动程序实现 了 SQLGetFunctions，驱动管理器会调用驱动中的该函数。否则，它会执行该函数本身。

Syntax

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

Arguments

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 值列表，请参见“注释”中的表格。

支持Ptr
[输出]如果 FunctionID 识别出单个 ODBC 函数， SupportedPtr 指向一个 SQLUSMALLINT 值，若该函数被驱动支持则SQL_TRUE，若不支持则SQL_FALSE。

如果 FunctionIdSQL_API_ODBC3_ALL_FUNCTIONS，SupportedPtr 指向一个元素数为 SQL_API_ODBC3_ALL_FUNCTIONS_SIZE 的 SQLSMALLINT 数组。该数组被驱动管理器视为4000位位图，可用于判断是否支持ODBC 3*.x*或更早函数。调用SQL_FUNC_EXISTS宏来确定函数支持。（参见“评论”。）ODBC 3*.x* 应用程序可以调用带有 SQL_API_ODBC3_ALL_FUNCTIONS的 SQLGetFunctions ，针对 ODBC 3*.x* 或 ODBC 2*.x* 驱动。

如果 FunctionIdSQL_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。

诊断

当 SQLGetFunctions 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_DBC 和 ConnectionHandle 的 Handle 来获得关联的 SQLSTATE 值。下表列出 了 SQLGetFunctions 通常返回的 SQLSTATE 值，并在此函数的上下文中对每个值进行了解释;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

SQLSTATE	Error	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。

Comments

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）宏用于确定在调用 SQLGetFunctions 并以 FunctionID 参数为 SQL_API_ODBC3_ALL_FUNCTIONS 后，支持 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。然而，SQLAllocHandle 或 SQLFreeHandle 的 HandleHandle（HandleType）参数为 SQL_HANDLE_DESC 不被支持，尽管这些函数返回了 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 函数

反馈

此页面是否有帮助？

Last updated on 2026-08-24