通过

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 指向一个 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针对 ODBC 3*.x* 或 ODBC 2*.x* 驱动程序调用 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时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_DBC 和 ConnectionHandle 的 Handle。 下表列出了 SQLGetFunctions 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
08S01 通信链接失败 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。
HY000 常规错误 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY010 函数序列错误 (DM) SQLGetFunctions 是在 SQLConnect、 SQLBrowseConnect 或 SQLDriverConnect 之前调用的。

为 ConnectionHandle 调用了 (DM) SQLBrowseConnect 并返回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 受支持。 这样做是因为这些函数是在驱动程序管理器中实现的。 如果 Unicode 函数存在，驱动程序管理器会将 ANSI 函数映射到相应的 Unicode 函数，并将 Unicode 函数映射到相应的 ANSI 函数（如果 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。 但是，尽管函数返回了SQL_TRUE，但不支持 handleType 参数为 SQL_HANDLE_DESC 的 SQLAllocHandle 或 SQLFreeHandle，因为在这种情况下没有要映射到的 ODBC 2*.x* 函数。

代码示例

以下三个示例演示了应用程序如何使用 SQLGetFunctions 来确定驱动程序是否支持 SQLTable、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 头文件