一致性
引入的版本：ODBC 1.0 标准符合性：ISO 92
总结
SQLDescribeCol 返回结果描述符——列名、类型、列大小、十进制数字和空可性——针对结果集中的某一列。 这些信息也可在IRD领域查阅。
Syntax
SQLRETURN SQLDescribeCol(
SQLHSTMT StatementHandle,
SQLUSMALLINT ColumnNumber,
SQLCHAR * ColumnName,
SQLSMALLINT BufferLength,
SQLSMALLINT * NameLengthPtr,
SQLSMALLINT * DataTypePtr,
SQLULEN * ColumnSizePtr,
SQLSMALLINT * DecimalDigitsPtr,
SQLSMALLINT * NullablePtr);
Arguments
StatementHandle
[输入]语句句柄。
列号
[输入]结果数据的列数，按列序递增顺序排列，从1开始。
ColumnNumber 参数也可以设置为 0，以描述书签列。
ColumnName
[输出]指向一个空终止缓冲区，返回列名。 该数值是从IRD的SQL_DESC_NAME字段读取的。 如果列未命名或无法确定列名，驱动返回一个空字符串。
如果 ColumnName 是 NULL，NameLengthPtr 仍然会返回 ColumnName 指向的缓冲区中可返回的总字符数（不包括字符数据的空终止字符）。
BufferLength
[输入]*ColumnName 缓冲区的长度，以字符为单位。
NameLengthPtr
[输出]指向缓冲区，返回*ColumnName中可返回的字符总数（不含空终止）。 如果可返回的字符数大于或等于 BufferLength，则 *ColumnName 中的列名会被截断为 BufferLength 减去空终止字符的长度。
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（对于书签列），SQL_BINARY在 *DataTypePtr 中返回可变长度书签。 （如果 ODBC 3 使用书签，则返回SQL_INTEGER。使用 ODBC 2 的 x 应用程序。x 驱动程序或 ODBC 2。使用 ODBC 3 的 x 应用程序。x driver.）
有关这些数据类型的更多信息，请参见附录D中的 SQL数据类型 。 有关特定于驱动程序的 SQL 数据类型的信息，请参阅驱动程序的文档。
列长Ptr
[输出]指向一个缓冲区，返回数据源列的大小（以字符为单位）。 如果无法确定列大小，驱动返回 0。 有关列大小的详细信息，请参阅 “列大小”、“小数位数”、“传输八进制数长度”和“显示大小 ”（附录 D：数据类型）。
DecimalDigitsPtr
[输出]指向缓冲区，返回数据源列的十进制数字。 如果小数点数无法确定或不适用，驱动返回 0。 有关十进制数字的更多信息，请参见附录D：数据类型中的 列大小、十进制数字、传输八重组长度和显示大小 。
NullablePtr
[输出]指向一个缓冲区，返回一个值，指示该列是否允许NULL值。 该数值是从IRD的SQL_DESC_NULLABLE字段读取的。 该值为下列值之一：
SQL_NO_NULLS：该列不允许NULL值。
SQL_NULLABLE：该列允许NULL值。
SQL_NULLABLE_UNKNOWN：驱动程序无法判断该列是否允许NULL值。
Returns
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_STILL_EXECUTING、SQL_ERROR或SQL_INVALID_HANDLE。
诊断
当 SQLDescribeCol 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值，Handle 为 SQL_HANDLE_STMT，Handle 为 StatementHandle。 下表列出 了SQLDescribeCol 通常返回的SQLSTATE值，并在此函数的上下文中解释了每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | Error | Description |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 01004 | 字符串数据，右截断 | 缓冲区 *ColumnName 不足以返回整个列名，因此列名被截断。 未截断列名的长度在 *NameLengthPtr. 中返回。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 07005 | 预备语句，非 光标规范 | 与 StatementHandle 关联的语句没有返回结果集。 没有柱子可以描述。 |
| 07009 | 无效描述子索引 | （DM） 参数 ColumnNumber 指定的值为 0，SQL_ATTR_USE_BOOKMARKS 语句选项为 SQL_UB_OFF。 参数 ColumnNumber 指定的值大于结果集的列数。 |
| 08S01 | 通信链接失败 | 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配故障 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY008 | 操作已取消 | 为 StatementHandle 启用了异步处理。 调用了该函数，在完成执行之前，对 StatementHandle 调用了 SQLCancel 或 SQLCancelHandle。 然后，在 StatementHandle 上再次调用该函数。 调用了函数，在完成执行之前，SQLCancel 或 SQLCancelHandle 从多线程应用程序中的不同线程调用 StatementHandle。 |
| HY010 | 函数序列错误 | （DM） 为与 StatementHandle 关联的连接句柄调用异步执行函数。 当调用 SQLDescribeCol 时，该异步函数仍在执行。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect 或 SQLMoreResults，并返回了SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 （DM） 为 StatementHandle 调用异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） 该函数在调用 SQLPrepare、 SQLExecute 或语句句柄上的目录函数之前被调用。 （DM） 为 StatementHandle 调用了 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos，并返回了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 能返回的 SQLSTATE 状态，这些状态取决于数据源何时评估与该语句关联的 SQL 语句。
出于性能考虑，应用程序不应在执行语句前调用 SQLDescribeCol 。
Comments
应用程序通常在调用 SQLPrepare 之后，以及调用 SQLExecute 之前或之后调用 SQLDescribeCol。 应用程序也可以在调用 SQLExecDirect 后调用 SQLDescribeCol。 有关详细信息，请参阅结果集元数据。
SQLDescribeCol 获取由 SELECT 语句生成的列名、类型和长度。 如果列是表达式，*ColumnName 要么是空字符串，要么是驱动程序定义的名称。
注释
ODBC 支持SQL_NULLABLE_UNKNOWN作为扩展，尽管开放组和 SQL 访问组呼叫层接口规范中未明确 SQLDescribeCol 的选项。
相关函数
| 有关以下内容的信息 | 请参阅 |
|---|---|
| 将缓冲区绑定到结果集中的列 | SQLBindCol |
| 取消语句处理 | SQLCancel |
| 返回有关结果集中的列的信息 | SQLColAttribute |
| 提取多行数据 | SQLFetch |
| 返回结果集列数 | SQLNumResultCols |
| 准备语句以供执行 | SQLPrepare |