SQLSpecialColumns 函数
一致性
引入的版本：ODBC 1.0 标准符合性：开放组
总结
SQLSpecialColumns 检索有关指定表中的列的以下信息：
唯一标识表中行的最佳列集。
当行中的任何值由事务更新时自动更新的列。
语法
SQLRETURN SQLSpecialColumns(
SQLHSTMT StatementHandle,
SQLSMALLINT IdentifierType,
SQLCHAR * CatalogName,
SQLSMALLINT NameLength1,
SQLCHAR * SchemaName,
SQLSMALLINT NameLength2,
SQLCHAR * TableName,
SQLSMALLINT NameLength3,
SQLSMALLINT Scope,
SQLSMALLINT Nullable);
参数
StatementHandle
[输入]语句句柄。
IdentifierType
[输入]要返回的列的类型。 必须是以下值之一：
SQL_BEST_ROWID：通过从列或列检索值，返回最佳列或列集，允许唯一标识指定表中的任何行。 列可以是专门为此目的设计的伪列（如 Oracle ROWID 或 Ingres TID 中），也可以是表任何唯一索引的列或列。
SQL_ROWVER：返回指定表中的列或列（如果有），当行中的任何值由任何事务（如 SQLBase ROWID 或 Sybase TIMESTAMP）更新时数据源自动更新的列。
CatalogName
[输入]表的目录名称。 如果驱动程序支持某些表的目录，但不支持其他表，例如当驱动程序从不同的 DBMS 检索数据时，空字符串 （“”） 表示没有目录的表。 CatalogName 不能包含字符串搜索模式。
如果 SQL_ATTR_METADATA_ID 语句属性设置为SQL_TRUE， 则 CatalogName 被视为标识符，并且其大小写不重要。 如果它是SQL_FAL标准版，则 CatalogName 是一个普通参数;它按字面处理，其大小写非常重要。 有关详细信息，请参阅目录函数中的参数。
NameLength1
[输入]*CatalogName 的长度（以字符为单位）。
SchemaName
[输入]表的架构名称。 如果驱动程序支持某些表的架构，但不支持其他表，例如当驱动程序从不同的 DBMS 检索数据时，空字符串 （“”） 表示那些没有架构的表。 SchemaName 不能包含字符串搜索模式。
如果将 SQL_ATTR_METADATA_ID 语句属性设置为SQL_TRUE， 则 SchemaName 被视为标识符，并且其大小写不重要。 如果它是SQL_FAL标准版，则 SchemaName 是一个普通参数;它按字面处理，并且其大小写非常重要。
NameLength2
[输入]*SchemaName 的长度（以字符为单位）。
TableName
[输入]表名。 此参数不能为 null 指针。 TableName 不能包含字符串搜索模式。
如果 SQL_ATTR_METADATA_ID 语句属性设置为SQL_TRUE， 则 TableName 被视为标识符，并且其大小写不重要。 如果它是SQL_FAL标准版，则 TableName 是一个普通参数;它按字面处理，其大小写非常重要。
NameLength3
[输入]*TableName 的长度（以字符为单位）。
范围
[输入]rowid 的最小所需范围。 返回的 rowid 的范围可能更大。 必须是下列选项之一：
SQL_SCOPE_CURROW：仅当放置在该行上时，rowid 才保证有效。 如果行被另一个事务更新或删除，则以后使用 rowid 重新选择可能不会返回行。
SQL_SCOPE_TRANSACTION：确保 rowid 在当前事务的持续时间内有效。
SQL_SCOPE_标准版SSION：确保 rowid 在会话（跨事务边界）期间有效。
可以为 Null
[输入]确定是否返回具有 NULL 值的特殊列。 必须是下列选项之一：
SQL_NO_NULLS：排除可以具有 NULL 值的特殊列。 某些驱动程序不支持SQL_NO_NULLS，如果指定了SQL_NO_NULLS，这些驱动程序将返回空结果集。 应用程序应为此情况做好准备，并且仅当绝对需要时才请求SQL_NO_NULLS。
SQL_NULLABLE：即使特殊列可以具有 NULL 值，也返回特殊列。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLSpecialColumns 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType of SQL_HANDLE_STMT 和 StatementHandle 句柄调用 SQLGetDiagRec来获取关联的 SQLSTATE 值。 下表列出了 SQLSpecialColumns 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 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 参数为 null 指针。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 调用 SQLSpecialColumns 时，此函数仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 为 StatementHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了SQL_N企业版D_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY090 | 字符串或缓冲区长度无效 | （DM） 长度参数之一的值小于 0，但不等于SQL_NTS。 长度参数之一的值超过了相应名称的最大长度值。 可以通过使用 InfoType 值调用 SQLGetInfo 来获取每个名称的最大长度：SQL_MAX_CATALOG_NAME_LEN、SQL_MAX_SCHEMA_NAME_LEN或SQL_MAX_TABLE_NAME_LEN。 |
| HY097 | 列类型范围外 | （DM） 指定了无效 的 IdentifierType 值。 |
| HY098 | 范围外的范围类型 | （DM） 指定了无效 的范围 值。 |
| HY099 | 可为 Null 的类型范围外 | （DM） 指定了无效 的可为 Null 值。 |
| HY117 | 由于未知事务状态，连接挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYC00 | 未实现可选功能 | 指定了目录，驱动程序或数据源不支持目录。 指定了架构，驱动程序或数据源不支持架构。 驱动程序或数据源不支持SQL_ATTR_CONCURRENCY和SQL_ATTR_CURSOR_TYPE语句属性的当前设置的组合。 SQL_ATTR_U标准版_BOOKMARKS语句属性设置为SQL_UB_VARIABLE，SQL_ATTR_CURSOR_TYPE语句属性设置为驱动程序不支持书签的游标类型。 |
| HYT00 | 已超时 | 在数据源返回请求的结果集之前，查询超时期限已过期。 超时期限通过 SQLSetStmtAttr 设置，SQL_ATTR_QUERY_TIMEOUT。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSet连接Attr 设置的，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 StatementHandle 关联的驱动程序不支持该函数。 |
| IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时，轮询将被禁用。 |
| IM018 | 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 | 如果句柄上的上一个函数调用返回SQL_STILL_EXECUTING并且启用通知模式， 则必须在句柄上调用 SQLCompleteAsync 才能执行后期处理并完成操作。 |
注释
当 IdentifierType 参数SQL_BEST_ROWID时，SQLSpecialColumns 返回唯一标识表中每一行的列或列。 这些列始终可用于 选择列表 或 WHERE 子句。 SQLColumns 用于返回表列的各种信息，不一定返回唯一标识每行的列，也不一定返回事务更新行中的任何值时自动更新的列。 例如， SQLColumns 可能不会返回 Oracle 伪列 ROWID。 这就是为什么 SQLSpecialColumns 用于返回这些列的原因。 有关详细信息，请参阅数据目录的用法。
注意
有关 ODBC 目录函数的常规用途、参数和返回数据的详细信息，请参阅 目录函数。
如果没有唯一标识表中每一行的列，SQLSpecialColumns 将返回一个无行的行集;对语句的 SQLFetch 或 SQLFetchScroll 的后续调用将返回SQL_NO_DATA。
如果 IdentifierType、Scope 或 Nullable 参数指定数据源不支持的特征，SQLSpecialColumns 将返回空的结果集。
如果 SQL_ATTR_METADATA_ID 语句属性设置为 SQL_TRUE， 则 CatalogName、 SchemaName 和 TableName 参数被视为标识符，因此在某些情况下，它们不能设置为 null 指针。 （有关详细信息，请参阅 目录函数中的参数。
SQLSpecialColumns 以按 SCOPE 排序的标准结果集返回结果。
已为 ODBC 3.x 重命名以下列。 列名更改不会影响向后兼容性，因为应用程序按列号绑定。
| ODBC 2.0 列 | ODBC 3.x 列 |
|---|---|
| PRECISION | COLUMN_SIZE |
| LENGTH | BUFFER_LENGTH |
| SCALE | DECIMAL_DIGITS |
若要确定COLUMN_NAME列的实际长度，应用程序可以使用SQL_MAX_COLUMN_NAME_LEN选项调用 SQLGetInfo 。
下表列出了结果集中的列。 驱动程序可以定义列 8 以外的其他列（P标准版UDO_COLUMN）。 应用程序应从结果集末尾倒计时，而不是指定显式序号位置来访问特定于驱动程序的列。 有关详细信息，请参阅 目录函数返回的数据。
| 列名称 | Column number | 数据类型 | 备注 |
|---|---|---|---|
| SCOPE （ODBC 1.0） | 1 | Smallint | rowid 的实际范围。 包含以下值之一： SQL_SCOPE_CURROW SQL_SCOPE_TRANSACTION SQL_SCOPE_标准版SSION 当 IdentifierType SQL_ROWVER时返回 NULL。 有关每个值的说明，请参阅本节前面的“语法”中的 Scope 说明。 |
| COLUMN_NAME （ODBC 1.0） | 2 | Varchar 非 NULL | 列名称。 驱动程序返回一个没有名称的列的空字符串。 |
| DATA_TYPE （ODBC 1.0） | 3 | Smallint（非 NULL） | SQL 数据类型。 这可以是 ODBC SQL 数据类型或特定于驱动程序的 SQL 数据类型。 有关有效的 ODBC SQL 数据类型的列表，请参阅 SQL 数据类型。 有关特定于驱动程序的 SQL 数据类型的信息，请参阅驱动程序的文档。 |
| TYPE_NAME （ODBC 1.0） | 4 | Varchar 非 NULL | 数据源依赖数据类型名称;例如，“CHAR”、“VARCHAR”、“MONEY”、“LONG VARBINARY”或“CHAR（） FOR BIT DATA”。 |
| COLUMN_SIZE （ODBC 1.0） | 5 | Integer | 数据源上的列的大小。 有关列大小的详细信息，请参阅 列大小、小数位数、传输八进制长度和显示大小。 |
| BUFFER_LENGTH （ODBC 1.0） | 6 | Integer | 如果指定了SQL_C_DEFAULT，则 SQLGetData 或 SQLFetch 操作上传输的数据的长度（以字节为单位）。 对于数值数据，此大小可能与存储在数据源上的数据的大小不同。 此值可能与字符数据的COLUMN_SIZE列不同。 有关详细信息，请参阅 列大小、小数位数、传输八进制数长度和显示大小。 |
| DECIMAL_DIGITS （ODBC 1.0） | 7 | Smallint | 数据源中列的十进制数字。 对于不适用十进制数字的数据类型，返回 NULL。 有关十进制数字的详细信息，请参阅 列大小、小数位数、传输八进制数长度和显示大小。 |
| P标准版UDO_COLUMN （ODBC 2.0） | 8 | Smallint | 指示列是否为伪列，例如 Oracle ROWID： SQL_PC_UNKNOWN SQL_PC_NOT_P标准版UDO SQL_PC_P标准版UDO 注意：为了获得最大的互操作性，不应使用 SQLGetInfo 返回的标识符引号字符来引用伪列。 |
应用程序检索SQL_BEST_ROWID的值后，应用程序可以使用这些值在定义的范围内重新选择该行。 标准版LECT 语句保证不返回任何行或一行。
如果应用程序根据 rowid 列或列重新选择行，并且找不到该行，则应用程序可以假定该行已删除或已修改 rowid 列。 相反的是：即使 rowid 未更改，行中的其他列也可能已更改。
为列类型返回的列SQL_BEST_ROWID对于需要在结果集中向前和后退以从一组行检索最新数据的应用程序非常有用。 确保 rowid 的列或列在该行上定位时不会更改。
即使游标未放置在行上，rowid 的列或列也可能保持有效;应用程序可以通过检查结果集中的 SCOPE 列来确定这一点。
为列类型返回的列SQL_ROWVER对于需要能够检查给定行中的任何列在使用 rowid 重新选择行时是否已更新这些列的应用程序非常有用。 例如，使用 rowid 重新选择行后，应用程序可以将SQL_ROWVER列中以前的值与刚刚提取的值进行比较。 如果SQL_ROWVER列中的值与上一个值不同，应用程序可以通知用户显示的数据已更改。
代码示例
有关类似函数的代码示例，请参阅 SQLColumns。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol 函数 |
| 取消语句处理 | SQLCancel 函数 |
| 返回表或表中的列 | SQLColumns 函数 |
| 提取单行或仅向前方向的数据块 | SQLFetch 函数 |
| 提取数据块或滚动结果集 | SQLFetchScroll 函数 |
| 返回主键的列 | SQLPrimaryKeys 函数 |