SQLGetDescRec 函数

一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92

摘要
SQLGetDescRec 返回描述符记录的多个字段的当前设置或值。 返回的字段描述列或参数数据的名称、数据类型和存储。

语法

  
SQLRETURN SQLGetDescRec(  
      SQLHDESC        DescriptorHandle,  
      SQLSMALLINT     RecNumber,  
      SQLCHAR *       Name,  
      SQLSMALLINT     BufferLength,  
      SQLSMALLINT *   StringLengthPtr,  
      SQLSMALLINT *   TypePtr,  
      SQLSMALLINT *   SubTypePtr,  
      SQLLEN *        LengthPtr,  
      SQLSMALLINT *   PrecisionPtr,  
      SQLSMALLINT *   ScalePtr,  
      SQLSMALLINT *   NullablePtr);  

参数

DescriptorHandle
[输入]描述符句柄。

RecNumber
[输入]指示应用程序从中查找信息的描述符记录。 描述符记录从 1 开始编号，记录编号 0 为书签记录。 RecNumber 参数必须小于或等于 SQL_DESC_COUNT 的值。 如果 RecNumber 小于或等于 SQL_DESC_COUNT但行不包含列或参数的数据，则对 SQLGetDescRec 的 调用将返回字段的默认值。 (有关详细信息，请参阅 SQLSetDescField.) 中的“初始化描述符字段”

名称
[输出]指向缓冲区的指针，在缓冲区中返回描述符记录的SQL_DESC_NAME字段。

如果 Name 为 NULL，StringLengthPtr 仍将返回总字符数， (不包括字符数据的 null 终止字符数，) Name 指向的缓冲区中返回。

BufferLength
[输入]*名称 缓冲区的长度（以字符为单位）。

StringLengthPtr
[输出]指向缓冲区的指针，该缓冲区可返回 *Name 缓冲区中可返回的数据字符数，不包括 null 终止字符。 如果字符数大于或等于 BufferLength，则*Name 中的数据将被截断为 BufferLength 减去 null 终止字符的长度，并由驱动程序以 null 结尾。

TypePtr
[输出]指向缓冲区的指针，其中返回描述符记录SQL_DESC_TYPE字段的值。

SubTypePtr
[输出]对于类型为 SQL_DATETIME 或 SQL_INTERVAL 的记录，这是指向缓冲区的指针，用于返回SQL_DESC_DATETIME_INTERVAL_CODE字段的值。

LengthPtr
[输出]指向缓冲区的指针，其中返回描述符记录SQL_DESC_OCTET_LENGTH字段的值。

PrecisionPtr
[输出]指向缓冲区的指针，用于返回描述符记录SQL_DESC_PRECISION字段的值。

ScalePtr
[输出]指向缓冲区的指针，用于返回描述符记录SQL_DESC_SCALE字段的值。

NullablePtr
[输出]指向缓冲区的指针，其中返回描述符记录SQL_DESC_NULLABLE字段的值。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR、SQL_NO_DATA或SQL_INVALID_HANDLE。

如果 RecNumber 大于当前描述符记录数，则返回SQL_NO_DATA。

如果 DescriptorHandle 是 IRD 句柄，并且语句处于准备或已执行状态，但没有与之关联的打开游标，则返回SQL_NO_DATA。

诊断

当 SQLGetDescRec 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过使用 handleType SQL_HANDLE_DESC 和 Handle ofDescriptorHandle 调用 SQLGetDiagRec 来获取关联的 SQLSTATE 值。 下表列出了 SQLGetDescRec 通常返回的 SQLSTATE 值，并解释了此函数上下文中的每个值：表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATE 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。

SQLSTATE	错误	说明
01000	常规警告	特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01004	字符串数据，右截断	缓冲区 *Name 不够大，无法返回整个描述符字段。 因此，字段被截断。 未构造的描述符字段的长度在 *StringLengthPtr 中返回。 (函数返回 SQL_SUCCESS_WITH_INFO.)
07009	描述符索引无效	FieldIdentifier 参数是记录字段，RecNumber 参数设置为 0，DescriptorHandle 参数是 IPD 句柄。 (DM) RecNumber 参数设置为 0，SQL_ATTR_USE_BOOKMARKS 语句属性设置为 SQL_UB_OFF， DescriptorHandle 参数是 IRD 句柄。 RecNumber 参数小于 0。
08S01	通信链接失败	在函数完成处理之前，驱动程序与所连接的数据源之间的通信链接失败。
HY000	常规错误	发生错误，其中没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 SQLGetDiagRec 在 *MessageText 缓冲区中返回的错误消息描述了错误及其原因。
HY001	内存分配错误	驱动程序无法分配支持执行或完成函数所需的内存。
HY007	未准备关联的语句	DescriptorHandle 与 IRD 关联，关联的语句句柄未处于准备或已执行状态。
HY010	函数序列错误	(DM) DescriptorHandle 与 一个 StatementHandle 相关联，其中异步执行的函数 () 调用，并且调用此函数时仍在执行。 (DM) DescriptorHandle 与为其调用 SQLExecute、SQLExecDirect、SQLBulkOperations 或 SQLSetPos 并返回SQL_NEED_DATA的 StatementHandle 相关联。 在针对所有数据执行参数或列发送数据之前调用了此函数。 (DM) 为与 DescriptorHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLGetDescRec 时，此异步函数仍在执行。
HY013	内存管理错误	无法处理函数调用，因为无法访问基础内存对象，可能是由于内存不足。
HY117	由于事务状态未知，连接已暂停。 仅允许断开连接和只读函数。	(DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。
HYT01	超过连接超时时间	在数据源响应请求之前，连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置。
IM001	驱动程序不支持此函数	(DM) 与 DescriptorHandle 关联的驱动程序不支持函数。

注释

应用程序可以调用 SQLGetDescRec 来检索单个列或参数的以下描述符字段的值：

• SQL_DESC_NAME

• SQL_DESC_TYPE

• 类型为SQL_DATETIME或SQL_INTERVAL) 的记录的SQL_DESC_DATETIME_INTERVAL_CODE (

• SQL_DESC_OCTET_LENGTH

• SQL_DESC_PRECISION

• SQL_DESC_SCALE

• SQL_DESC_NULLABLE

SQLGetDescRec 不检索标头字段的值。

应用程序可以通过将对应于字段的参数设置为 null 指针来防止返回字段的设置。

当应用程序调用 SQLGetDescRec 来检索未为特定描述符类型定义的字段的值时，函数将返回SQL_SUCCESS但为字段返回的值未定义。 例如，为 APD 或 ARD 的 SQL_DESC_NAME 或 SQL_DESC_NULLABLE 字段调用 SQLGetDescRec 将返回SQL_SUCCESS但返回字段的未定义值。

当应用程序调用 SQLGetDescRec 来检索为特定描述符类型定义但尚未设置默认值且尚未设置的字段的值时，函数将返回SQL_SUCCESS但为该字段返回的值未定义。 有关详细信息，请参阅 SQLSetDescField 中的“描述符字段的初始化”。

还可以通过调用 SQLGetDescField 单独检索字段的值。 有关描述符标头或记录中的字段的说明，请参阅 SQLSetDescField。 有关描述符的详细信息，请参阅 描述符。

相关函数

有关以下方面的信息	请参阅
绑定列	SQLBindCol 函数
绑定参数	SQLBindParameter 函数
获取描述符字段	SQLGetDescField 函数
设置多个描述符字段	SQLSetDescRec 函数

另请参阅

ODBC API 参考
ODBC 头文件