一致性
推出版本：ODBC 3.0 标准合规：ISO 92
总结
SQLGetDescField 返回描述符记录中单个字段的当前设置或值。
Syntax
SQLRETURN SQLGetDescField(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT FieldIdentifier,
SQLPOINTER ValuePtr,
SQLINTEGER BufferLength,
SQLINTEGER * StringLengthPtr);
Arguments
DescriptorHandle
[输入]描述符的使用。
RecNumber
[输入]表示应用程序获取信息的描述符记录。 描述符记录从0开始编号，记录编号0为书签记录。 如果 FieldIdentifier 参数指示的是 header 字段，则忽略 RecNumber 。 如果 RecNumber 小于或等于 SQL_DESC_COUNT，但该行不包含列或参数的数据，调用 SQLGetDescField 将返回字段的默认值。 （更多信息请参见 SQLSetDescField 中的“描述符字段初始化”。）
FieldIdentifier
[输入]表示要返回值的描述符字段。 更多信息请参见 SQLSetDescField 中的“字段标识符参数”部分。
ValuePtr
[输出]指向一个缓冲区，返回描述符信息。 数据类型取决于 字段标识符的值。
如果 ValuePtr 是整数类型，应用程序应使用 SQLULEN 缓冲区，并将值初始化为 0，然后再调用该函数，因为有些驱动程序可能只写缓冲区的低 32 位或 16 位，而不更改高阶位。
如果 ValuePtr 是 NULL，StringLengthPtr 仍然会返回 ValuePtr 指向的缓冲区中可返回的总字节数（不含字符数据的空终止字符）。
BufferLength
[输入]如果 FieldIdentifier 是 ODBC 定义的字段，且 ValuePtr 指向一个字符串或二进制缓冲区，那么该参数应为 *ValuePtr 的长度。 如果 字段标识 符是ODBC定义的字段，且*ValuePtr 是整数字段，则忽略 缓冲长度 。 如果 *ValuePtr 中的值属于 Unicode 数据类型（调用 SQLGetDescFieldW 时）， BufferLength 参数必须是偶数。
如果 FieldIdentifier 是驱动程序定义的字段，应用程序通过设置 BufferLength 参数向驱动程序管理器指示字段的性质。 缓冲长度 可以有以下数值：
如果 *ValuePtr 是指向字符字符串的指针，那么 BufferLength 就是该字符串或 SQL_NTS 的长度。
如果 *ValuePtr 是指向二进制缓冲区的指针，那么应用程序将 SQL_LEN_BINARY_ATTR（长度）宏的结果置入 BufferLength。 这会使 缓冲长度为负值。
如果 *ValuePtr 指向非字符字符串或二进制字符串的值，那么 BufferLength 应具有 SQL_IS_POINTER 值。
如果 *ValuePtr 包含固定长度的数据类型，那么 缓冲长度 可以是SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT或SQL_IS_USMALLINT，视情况而定。
StringLengthPtr
[输出]指向返回*ValuePtr中可用字节总数（不含空终止字符所需的字节数）的缓冲区。
Returns
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 值，Handle 为 SQL_HANDLE_STMT，Handle 为 StatementHandle。 下表列出 了SQLGetDescField 通常返回的SQLSTATE值，并在此函数的上下文中解释了每个值;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | Error | Description |
|---|---|---|
| 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 句柄。 （只有当描述符与语句句柄关联时，才能对显式分配的描述符返回该错误。） FieldIdentifier 参数是记录字段，RecNumber 参数是 0，DescriptorHandle 参数是 IPD 句柄。 RecNumber 论点小于 0。 |
| 08S01 | 通信链接失败 | 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY007 | 未准备好关联的语句 | DescriptorHandle 作为 IRD 关联了一个 StatementHandle ，且该关联的语句句柄尚未准备或执行。 |
| HY010 | 函数序列错误 | （DM） DescriptorHandle 关联到一个 StatementHandle，该 StatementHandle 调用了一个异步执行的函数（非这个），且在调用该函数时仍在执行。 （DM） DescriptorHandle 关联到一个 StatementHandle ，调用 SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 后返回SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 （DM） 为与 描述符关联的连接句柄调用了一个异步执行函数。 当调用 SQLGetDescField 函数时，该异步函数仍在运行。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY021 | 描述符信息不一致 | SQL_DESC_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE字段不构成有效的ODBC SQL类型、有效的驱动程序特定SQL类型（针对IPD）或有效的ODBC C类型（适用于APD或ARD）。 |
| HY090 | 字符串或缓冲区长度无效 | （DM） *ValuePtr 是一个字符字符串， BufferLength 小于零。 |
| HY091 | 无效描述符字段标识符 |
FieldIdentifier 不是 ODBC 定义的字段，也不是实现定义的值。 DescriptorHandle 的字段标识符未定义。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 关于暂停状态的更多信息，请参见 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置，SQL_ATTR_CONNECTION_TIMEOUT。 |
| IM001 | 驱动程序不支持此函数 | （DM） 与 描述符Handle 关联的驱动程序不支持该函数。 |
Comments
应用程序可以调用 SQLGetDescField 返回描述符记录中单个字段的值。 调用 SQLGetDescField 可以返回任何描述符类型中任意字段的设置，包括头字段、记录字段和书签字段。 应用程序可以通过反复调用 SQLGetDescField 来获得相同或不同描述符中多个字段的设置，顺序任意。 也可以调用SQLGetDescField返回驱动程序定义的描述符字段。
出于性能考虑，应用程序不应在执行语句前调用 SQLGetDescField 获取 IRD。
描述列或参数数据的名称、类型和存储的多个字段的设置，也可以通过一次调用 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 函数 |