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 函数 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈