SQLDescribeCol 函数
一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92
摘要
SQLDescribeCol 返回结果集中一列的结果描述符 - 列名、类型、列大小、十进制数字和可为空性。 此信息也可在 IRD 的字段中获取。
语法
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
参数
StatementHandle
[输入]语句句柄。
ColumnNumber
[输入]结果数据的列数，按顺序递增列顺序排序，从 1 开始。 ColumnNumber 参数也可以设置为 0 以描述书签列。
ColumnName
[输出]指向以 null 结尾的缓冲区的指针，该缓冲区将返回列名。 此值从 IRD 的“SQL_DESC_NAME”字段读取。 如果列未命名或无法确定列名，驱动程序将返回一个空字符串。
如果 ColumnName 为 NULL， 则 NameLengthPtr 仍将返回总字符数 (不包括字符数据的 null 终止字符数，) ColumnName 指向的缓冲区中返回。
BufferLength
[输入]*ColumnName 缓冲区的长度（以字符为单位）。
NameLengthPtr
[输出]指向缓冲区的指针，该缓冲区将返回 (排除 null 终止) 可在 *ColumnName 中返回的字符总数。 如果可返回的字符数大于或等于 BufferLength，则*ColumnName 中的列名将被截断为 BufferLength 减去 null 终止字符的长度。
DataTypePtr
[输出]指向要在其中返回列的 SQL 数据类型的缓冲区的指针。 此值从 IRD 的“SQL_DESC_CONCISE_TYPE”字段读取。 这是 SQL 数据类型中的值之一，或特定于驱动程序的 SQL 数据类型。 如果无法确定数据类型，驱动程序将返回SQL_UNKNOWN_TYPE。
在 ODBC 3 中。x、SQL_TYPE_DATE、SQL_TYPE_TIME或SQL_TYPE_TIMESTAMP分别在 *DataTypePtr 中返回日期、时间或时间戳数据;在 ODBC 2 中。返回 x、SQL_DATE、SQL_TIME 或 SQL_TIMESTAMP。 当 ODBC 2 时，驱动程序管理器执行所需的映射。x 应用程序正在使用 ODBC 3。x 驱动程序或当 ODBC 3 时。x 应用程序正在使用 ODBC 2。x 驱动程序。
当书签列) 的 ColumnNumber 等于 0 (时，将在 *DataTypePtr 中为可变长度书签返回SQL_BINARY。 如果 ODBC 3 使用书签，则返回 (SQL_INTEGER。使用 ODBC 2 的 x 应用程序。x 驱动程序或由 ODBC 2。使用 ODBC 3 的 x 应用程序。x driver.)
有关这些数据类型的详细信息，请参阅附录 D：数据类型中的 SQL 数据类型。 有关特定于驱动程序的 SQL 数据类型的信息，请参阅驱动程序的文档。
ColumnSizePtr
[输出]指向缓冲区的指针，其中返回数据源上列) 以字符为单位的大小 (。 如果无法确定列大小，驱动程序将返回 0。 有关列大小的详细信息，请参阅附录 D：数据类型中的 列大小、十进制数字、传输八进制长度和显示大小 。
DecimalDigitsPtr
[输出]指向缓冲区的指针，该缓冲区将返回数据源上列的十进制位数。 如果无法确定或不适用小数位数，驱动程序将返回 0。 有关十进制数字的详细信息，请参阅附录 D：数据类型中的 列大小、十进制数字、传输八进制长度和显示大小 。
NullablePtr
[输出]指向缓冲区的指针，该缓冲区将返回一个值，该值指示列是否允许 NULL 值。 此值从 IRD 的“SQL_DESC_NULLABLE”字段中读取。 值为以下值之一：
SQL_NO_NULLS：列不允许 NULL 值。
SQL_NULLABLE：列允许 NULL 值。
SQL_NULLABLE_UNKNOWN：驱动程序无法确定列是否允许 NULL 值。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLDescribeCol 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType 为 SQL_HANDLE_STMT 和 Handle of StatementHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLDescribeCol 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | 缓冲区 *ColumnName 不够大，无法返回整个列名称，因此列名被截断。 非结构化列名的长度在 *NameLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 07005 | 准备语句不是 游标规范 | 与 StatementHandle 关联的语句未返回结果集。 没有要描述的列。 |
| 07009 | 描述符索引无效 | (DM) 为参数 ColumnNumber 指定的值等于 0，并且SQL_UB_OFF SQL_ATTR_USE_BOOKMARKS 语句选项。 为参数 ColumnNumber 指定的值大于结果集中的列数。 |
| 08S01 | 通信链接失败 | 在函数完成处理之前，驱动程序与所连接的数据源之间的通信链接失败。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配失败 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 已为 StatementHandle 启用异步处理。 调用了函数，在它完成执行之前，在 StatementHandle 上调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用函数。 函数已调用，在它完成执行之前，在 StatementHandle 上从多线程应用程序中的不同线程调用 SQLCancel 或 SQLCancelHandle。 |
| HY010 | 函数序列错误 | (DM) 为与 StatementHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLDescribeCol 时，此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 StatementHandle 调用并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流参数的数据之前调用的。 (DM) 为 StatementHandle 调用了异步执行的函数， (不是此函数) ，在调用此函数时仍在执行。 (DM) 在对语句句柄调用 SQLPrepare、 SQLExecute 或目录函数之前调用函数。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 已为 StatementHandle 调用，并返回SQL_NEED_DATA。 在针对所有数据执行参数或列发送数据之前调用了此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) 为参数 BufferLength 指定的值小于 0。 |
| HY117 | 由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与 StatementHandle 关联的驱动程序不支持 函数。 |
| IM017 | 在异步通知模式下禁用轮询 | 每当使用通知模型时，将禁用轮询。 |
| IM018 | 尚未调用 SQLCompleteAsync 来完成此句柄上的上一个异步操作。 | 如果对句柄的上一个函数调用返回SQL_STILL_EXECUTING并且启用了通知模式，则必须在句柄上调用 SQLCompleteAsync 以执行后期处理并完成操作。 |
SQLDescribeCol 可以返回 SQLPrepare 或 SQLExecute 在 SQLPrepare 之后和 SQLExecute 调用时可由 SQLPrepare 或 SQLExecute 返回的任何 SQLSTATE，具体取决于数据源评估与语句句柄关联的 SQL 语句的时间。
出于性能原因，应用程序在执行语句之前不应调用 SQLDescribeCol 。
注释
应用程序通常在调用 SQLPrepare 之后以及对 SQLExecute 的关联调用之前或之后调用 SQLDescribeCol。 应用程序还可以在调用 SQLExecDirect 后调用 SQLDescribeCol。 有关详细信息，请参阅 结果集元数据。
SQLDescribeCol 检索 SELECT 语句生成的列名、类型和长度。 如果该列是表达式，则 *ColumnName 是空字符串或驱动程序定义的名称。
注意
ODBC 支持将 SQL_NULLABLE_UNKNOWN 作为扩展，即使开放组和 SQL 访问组调用级别接口规范未指定 SQLDescribeCol 的选项。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol |
| 取消语句处理 | SQLCancel |
| 返回有关结果集中列的信息 | SQLColAttribute |
| 提取多行数据 | SQLFetch |
| 返回结果集列数 | SQLNumResultCols |
| 准备要执行的语句 | SQLPrepare |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈