SQLStatistics 函数
一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92
摘要
SQLStatistics 检索有关单个表以及与该表关联的索引的统计信息列表。 驱动程序将信息作为结果集返回。
语法
SQLRETURN SQLStatistics(
SQLHSTMT StatementHandle,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLUSMALLINT Unique,
SQLUSMALLINT Reserved);
参数
StatementHandle
[输入]语句句柄。
CatalogName
[输入]目录名称。 如果驱动程序支持某些表的目录，但不支持其他表的目录，例如当驱动程序从不同的 DBMS 检索数据时，空字符串 (“”) 指示那些没有目录的表。 CatalogName 不能包含字符串搜索模式。
如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， 则 CatalogName 被视为标识符，其大小写不重要。 如果它是SQL_FALSE， 则 CatalogName 是一个普通参数;它按字面处理，其大小写很重要。 有关详细信息，请参阅 目录函数中的参数。
NameLength1
[输入]*CatalogName 的长度（以字符为单位）。
SchemaName
[输入]架构名称。 如果驱动程序支持某些表的架构，但不支持其他表的架构，例如，当驱动程序从不同的 DBMS 检索数据时，空字符串 (“”) 指示那些没有架构的表。 SchemaName 不能包含字符串搜索模式。
如果将 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， 则 SchemaName 被视为标识符，其大小写并不重要。 如果它是SQL_FALSE， 则 SchemaName 是一个普通参数;它按字面处理，其大小写很重要。
NameLength2
[输入]长度（以 *SchemaName 的字符为单位）。
TableName
[输入]表名。 此参数不能为 null 指针。 SchemaName 不能包含字符串搜索模式。
如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， 则 TableName 被视为标识符，其大小写不重要。 如果SQL_FALSE， 则 TableName 是一个普通参数;它按字面处理，其大小写很重要。
NameLength3
[输入]*TableName 的长度（以字符为单位）。
唯一
[输入]索引类型：SQL_INDEX_UNIQUE或SQL_INDEX_ALL。
Reserved
[输入]指示结果集中 CARDINALITY 和 PAGES 列的重要性。 以下选项仅影响 CARDINALITY 和 PAGES 列的返回;即使不返回 CARDINALITY 和 PAGES，也会返回索引信息。
SQL_ENSURE请求驱动程序无条件地检索统计信息。 仅符合开放组标准且不支持 ODBC 扩展 (驱动程序将无法支持 SQL_ENSURE.)
SQL_QUICK请求驱动程序检索 CARDINALITY 和 PAGES，前提是它们可从服务器随时可用。 在这种情况下，驱动程序不能保证是最新值。 写入开放组标准的 (应用程序将始终从符合 ODBC 3.x 的 drivers.SQL_QUICK行为)
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLStatistics 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT， 句柄 为 StatementHandle。 下表列出了通常由 SQLStatistics 返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 08S01 | 通信链接失败 | 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。 |
| 24000 | 游标状态无效 | 在 StatementHandle 上打开了一个游标，并且已调用 SQLFetch 或 SQLFetchScroll。 如果 SQLFetch 或 SQLFetchScroll 未返回SQL_NO_DATA，则驱动程序管理器将返回此错误;如果 SQLFetch 或 SQLFetchScroll 已返回SQL_NO_DATA，则驱动程序会返回此错误。 在 StatementHandle 上打开了游标，但尚未调用 SQLFetch 或 SQLFetchScroll。 |
| 40001 | 序列化失败 | 由于与另一个事务发生资源死锁，事务已回滚。 |
| 40003 | 语句完成未知 | 关联的连接在执行此函数期间失败，并且无法确定事务的状态。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 已为 StatementHandle 启用异步处理。 调用了函数，在它完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle，然后在 StatementHandle 上再次调用该函数。 函数已调用，在它完成执行之前， SQLCancel 或 SQLCancelHandle 是从多线程应用程序中的不同线程在 StatementHandle 上调用的。 |
| HY009 | null 指针的使用无效 | TableName 参数为空指针。 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， CatalogName 参数为空指针，SQL_CATALOG_NAME InfoType 返回支持的目录名称。 (DM) SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， SchemaName 参数为空指针。 |
| HY010 | 函数序列错误 | (DM) 为 与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLStatistics 函数时，此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。 (DM) 为 StatementHandle 调用了异步执行的函数 (不是此函数) ，并且调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用并返回SQL_NEED_DATA。 在为所有数据执行时参数或列发送数据之前调用了此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) 其中一个名称长度参数的值小于 0，但不等于SQL_NTS。 其中一个名称长度参数的值超过了相应名称的最大长度值。 |
| HY100 | 唯一性选项类型范围外 | (DM) 指定了无效 的唯 一值。 |
| HY101 | 准确度选项类型范围外 | (DM) 指定了无效的 保留 值。 |
| HY117 | 由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | 指定了目录，驱动程序或数据源不支持目录。 指定了架构，驱动程序或数据源不支持架构。 驱动程序或数据源不支持SQL_ATTR_CONCURRENCY和 SQL_ATTR_CURSOR_TYPE 语句属性的当前设置组合。 SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_VARIABLE，SQL_ATTR_CURSOR_TYPE 语句属性设置为驱动程序不支持书签的游标类型。 |
| HYT00 | 超时时间已到 | 查询超时期限在数据源返回请求的结果集之前过期。 超时期限是通过 SQLSetStmtAttr SQL_ATTR_QUERY_TIMEOUT设置的。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与 StatementHandle 关联的驱动程序不支持 函数。 |
| IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时，将禁用轮询。 |
| IM018 | 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 | 如果对句柄的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式，则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。 |
注释
SQLStatistics 以标准结果集的形式返回有关单个表的信息，按NON_UNIQUE、TYPE、INDEX_QUALIFIER、INDEX_NAME和ORDINAL_POSITION排序。 结果集将表结果集) 的 CARDINALITY 和 PAGES 列中的统计信息 (与每个索引的相关信息合并在一起。 有关如何使用此信息的信息，请参阅 目录数据的使用。
若要确定TABLE_CAT、TABLE_SCHEM、TABLE_NAME和COLUMN_NAME列的实际长度，应用程序可以使用SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN、SQL_MAX_TABLE_NAME_LEN和SQL_MAX_COLUMN_NAME_LEN选项调用 SQLGetInfo 。
注意
有关 ODBC 目录函数的常规用法、参数和返回数据的详细信息，请参阅 目录函数。
以下列已重命名为 ODBC 3.x。 列名更改不会影响向后兼容性，因为应用程序按列号绑定。
| ODBC 2.0 列 | ODBC 3.x 列 |
|---|---|
| TABLE_QUALIFIER | TABLE_CAT |
| TABLE_OWNER | TABLE_SCHEM |
| SEQ_IN_INDEX | ORDINAL_POSITION |
| COLLATION | ASC_OR_DESC |
下表列出了结果集中的列。 第 13 列以外的其他列 (FILTER_CONDITION) 可由驱动程序定义。 应用程序应通过从结果集末尾倒计时（而不是指定显式序号位置）来访问特定于驱动程序的列。 有关详细信息，请参阅 目录函数返回的数据。
| 列名称 | 列号 | 数据类型 | 注释 |
|---|---|---|---|
| TABLE_CAT (ODBC 1.0) | 1 | Varchar | 统计信息或索引所应用到的表的目录名称;如果不适用于数据源，则为 NULL。 如果驱动程序支持某些表的目录，但不支持其他表的目录，例如当驱动程序从不同的 DBMS 检索数据时，它将为没有目录的表返回空字符串 (“”) 。 |
| TABLE_SCHEM (ODBC 1.0) | 2 | Varchar | 统计信息或索引所应用到的表的架构名称;如果不适用于数据源，则为 NULL。 如果驱动程序支持某些表的架构，但不支持其他表的架构，例如当驱动程序从不同的 DBMS 检索数据时，它会为没有架构的表返回空字符串 (“”) 。 |
| TABLE_NAME (ODBC 1.0) | 3 | Varchar 非 NULL | 统计信息或索引所应用到的表的表名。 |
| NON_UNIQUE (ODBC 1.0) | 4 | Smallint | 指示索引是否不允许重复值： SQL_TRUE索引值是否可以为非唯一值。 SQL_FALSE索引值是否必须唯一。 如果SQL_TABLE_STAT TYPE，则返回 NULL。 |
| INDEX_QUALIFIER (ODBC 1.0) | 5 | Varchar | 用于限定执行 DROP INDEX 的索引名称的标识符;如果数据源不支持索引限定符，或者如果 TYPE SQL_TABLE_STAT，则返回 NULL。 如果此列中返回非 null 值，则必须使用该值来限定 DROP INDEX 语句上的索引名称;否则，应使用TABLE_SCHEM来限定索引名称。 |
| INDEX_NAME (ODBC 1.0) | 6 | Varchar | 索引名称;如果SQL_TABLE_STAT TYPE，则返回 NULL。 |
| 类型 (ODBC 1.0) | 7 | Smallint（非 NULL） | 返回的信息类型： SQL_TABLE_STAT指示 CARDINALITY 或 PAGES 列) 中表 (的统计信息。 SQL_INDEX_BTREE指示 B 树索引。 SQL_INDEX_CLUSTERED指示聚集索引。 SQL_INDEX_CONTENT指示内容索引。 SQL_INDEX_HASHED指示哈希索引。 SQL_INDEX_OTHER指示另一种类型的索引。 |
| ORDINAL_POSITION (ODBC 1.0) | 8 | Smallint | 索引 (中的列序列号，从 1 个) 开始;如果SQL_TABLE_STAT TYPE，则返回 NULL。 |
| COLUMN_NAME (ODBC 1.0) | 9 | Varchar | 列名称。 如果列基于表达式（如 SALARY + BENEFITS），则返回表达式;如果无法确定表达式，则返回空字符串。 如果SQL_TABLE_STAT TYPE，则返回 NULL。 |
| ASC_OR_DESC (ODBC 1.0) | 10 | Char(1) | 列的排序顺序：“A”表示升序;“D”表示降序;如果数据源不支持列排序序列或SQL_TABLE_STAT TYPE，则返回 NULL。 |
| CARDINALITY (ODBC 1.0) | 11 | Integer | 表或索引的基数;如果 TYPE 为SQL_TABLE_STAT，则表中的行数;如果 TYPE 未SQL_TABLE_STAT，则索引中的唯一值数;如果值在数据源中不可用，则返回 NULL。 |
| PAGES (ODBC 1.0) | 12 | Integer | 用于存储索引或表的页数;如果 TYPE 为SQL_TABLE_STAT，则为表的页数;如果未SQL_TABLE_STAT TYPE，则为索引的页数;如果值在数据源中不可用，或者不适用于数据源，则返回 NULL。 |
| FILTER_CONDITION (ODBC 2.0) | 13 | Varchar | 如果索引是筛选索引，则这是筛选条件，例如 SALARY > 30000;如果无法确定筛选条件，则为空字符串。 如果索引不是筛选索引，则无法确定索引是筛选索引，还是SQL_TABLE_STAT TYPE。 |
如果结果集中的行对应于表，驱动程序会将 TYPE 设置为 SQL_TABLE_STAT，并将 NON_UNIQUE、INDEX_QUALIFIER、INDEX_NAME、ORDINAL_POSITION、COLUMN_NAME 和 ASC_OR_DESC 设置为 NULL。 如果 CARDINALITY 或 PAGES 在数据源中不可用，驱动程序会将其设置为 NULL。
代码示例
有关类似函数的代码示例，请参阅 SQLColumns。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 以仅向前方向提取单行或数据块。 | SQLFetch 函数 |
| 提取数据块或滚动浏览结果集 | SQLFetchScroll Function（SQLFetchScroll 函数） |
| 返回外键的列 | SQLForeignKeys 函数 |
| 返回主键的列 | SQLPrimaryKeys 函数 |