SQLGetDescField 函数
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
摘要
SQLGetDescField 返回描述符记录的单个字段的当前设置或值。
语法
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
参数
DescriptorHandle
[输入]描述符句柄。
RecNumber
[输入]指示应用程序从中查找信息的描述符记录。 描述符记录从 0 开始编号，记录号 0 为书签记录。 如果 FieldIdentifier 参数指示标头字段，则忽略 RecNumber 。 如果 RecNumber 小于或等于 SQL_DESC_COUNT 但行不包含列或参数的数据，则对 SQLGetDescField 的调用将返回字段的默认值。 (有关详细信息，请参阅 SQLSetDescField.)
FieldIdentifier
[输入]指示要返回其值的描述符的字段。 有关详细信息，请参阅 SQLSetDescField 中的“FieldIdentifier 参数”部分。
ValuePtr
[输出]指向要在其中返回描述符信息的缓冲区的指针。 数据类型取决于 FieldIdentifier 的值。
如果 ValuePtr 是整数类型，则应用程序应使用 SQLULEN 缓冲区，并在调用此函数之前将值初始化为 0，因为某些驱动程序可能只写入缓冲区的较低 32 位或 16 位，并保留高阶位不变。
如果 ValuePtr 为 NULL， 则 StringLengthPtr 仍将返回总字节数 (不包括 valuePtr 指向的缓冲区中可返回的字符数据的 null 终止字符) 。
BufferLength
[输入]如果 FieldIdentifier 是 ODBC 定义的字段，并且 ValuePtr 指向字符串或二进制缓冲区，则此参数应为 *ValuePtr 的长度。 如果 FieldIdentifier 是 ODBC 定义的字段，并且 *ValuePtr 是整数，则忽略 BufferLength 。 如果在调用 SQLGetDescFieldW) 时*ValuePtr 中的值为 Unicode 数据类型 (，则 BufferLength 参数必须是偶数。
如果 FieldIdentifier 是驱动程序定义的字段，则应用程序通过设置 BufferLength 参数向驱动程序管理器指示该字段的性质。 BufferLength 可以具有以下值：
如果 *ValuePtr 是指向字符串的指针，则 BufferLength 是字符串或SQL_NTS的长度。
如果 *ValuePtr 是指向二进制缓冲区的指针，则应用程序会将SQL_LEN_BINARY_ATTR (长度 的结果) 宏放在 BufferLength 中。 这会在 BufferLength 中放置一个负值。
如果 *ValuePtr 是指向字符串或二进制字符串以外的值的指针，则 BufferLength 的值应SQL_IS_POINTER。
如果 *ValuePtr 包含固定长度的数据类型，则 BufferLength 是SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT或SQL_IS_USMALLINT（视情况而定）。
StringLengthPtr
[输出]指向缓冲区的指针，该缓冲区将返回总字节数 (不包括可用于 *ValuePtr 中返回的 null 终止字符) 所需的字节数。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。
如果 RecNumber 大于当前描述符记录数，则返回SQL_NO_DATA。
如果 DescriptorHandle 是 IRD 句柄，并且语句处于准备或已执行状态，但没有与之关联的打开游标，则返回SQL_NO_DATA。
诊断
当 SQLGetDescField 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值，该 SQLGetDiagRec 的 HandleType 为 SQL_HANDLE_STMT，句 柄 为 StatementHandle。 下表列出了 SQLGetDescField 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 01004 | 字符串数据，右截断 | 缓冲区 *ValuePtr 不够大，无法返回整个描述符字段，因此该字段被截断。 未构造的描述符字段的长度在 *StringLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 07009 | 描述符索引无效 | (DM) RecNumber 参数等于 0，SQL_ATTR_USE_BOOKMARK语句属性SQL_UB_OFF， DescriptorHandle 参数是 IRD 句柄。 (仅当显式分配的描述符与语句 handle 相关联时，才能为显式分配的描述符返回此错误。) FieldIdentifier 参数为记录字段，RecNumber 参数为 0，DescriptorHandle 参数为 IPD 句柄。 RecNumber 参数小于 0。 |
| 08S01 | 通信链接失败 | 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY007 | 未准备关联的语句 | DescriptorHandle 与 StatementHandle 关联为 IRD，并且尚未准备或执行关联的语句句柄。 |
| HY010 | 函数序列错误 | (DM) DescriptorHandle 与 StatementHandle 相关联，该语句调用了异步执行的函数 (不是此) 函数，并在调用此函数时仍在执行。 (DM) DescriptorHandle 与为其调用 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos 并返回SQL_NEED_DATA的 StatementHandle 相关联。 在为所有数据执行时参数或列发送数据之前调用了此函数。 (DM) 为与 DescriptorHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLGetDescField 函数时，此异步函数仍在执行。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。 |
| HY021 | 描述符信息不一致 | SQL_DESC_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE字段不构成有效的 ODBC SQL 类型、针对 IPD) 的有效特定于驱动程序的 SQL 类型 (，也不构成用于 APD 或 ARD) 的有效 ODBC C 类型 (。 |
| HY090 | 无效的字符串或缓冲区长度 | (DM) *ValuePtr 是字符串， BufferLength 小于零。 |
| HY091 | 描述符字段标识符无效 | FieldIdentifier 不是 ODBC 定义的字段，也不是实现定义的值。 未为 DescriptorHandle 定义 FieldIdentifier。 |
| HY117 | 由于未知的事务状态，连接已挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与 DescriptorHandle 关联的驱动程序不支持函数。 |
注释
应用程序可以调用 SQLGetDescField 以返回描述符记录的单个字段的值。 调用 SQLGetDescField 可以返回任何描述符类型中任何字段的设置，包括标头字段、记录字段和书签字段。 应用程序可以通过对 SQLGetDescField 进行重复调用，以任意顺序获取相同或不同描述符中的多个字段的设置。 还可以调用 SQLGetDescField 以返回驱动程序定义的描述符字段。
出于性能原因，应用程序在执行语句之前不应调用 IRD 的 SQLGetDescField 。
还可以在对 SQLGetDescRec 的单个调用中检索描述列或参数数据的名称、数据类型和存储的多个字段的设置。 可以调用 SQLGetStmtAttr 以返回描述符标头中单个字段的设置，该字段也是语句属性。 SQLColAttribute、 SQLDescribeCol 和 SQLDescribeParam 返回记录或书签字段。
当应用程序调用 SQLGetDescField 来检索未为特定描述符类型定义的字段的值时，函数将返回SQL_SUCCESS但为字段返回的值未定义。 例如，为 APD 或 ARD 的SQL_DESC_NAME字段或SQL_DESC_NULLABLE字段调用 SQLGetDescField 将返回SQL_SUCCESS但返回字段的未定义值。
当应用程序调用 SQLGetDescField 来检索为特定描述符类型定义但没有默认值且尚未设置的字段的值时，函数将返回SQL_SUCCESS但为字段返回的值未定义。 有关描述符字段的初始化和字段说明的详细信息，请参阅 SQLSetDescField 中的“描述符字段的初始化”。 有关描述符的详细信息，请参阅 描述符。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 获取多个描述符字段 | SQLGetDescRec 函数 |
| 设置单个描述符字段 | SQLSetDescField 函数 |
| 设置多个描述符字段 | SQLSetDescRec 函数 |