SQLSetDescRec 函数
一致性
引入的版本：ODBC 3.0 标准符合性：ISO 92
摘要
SQLSetDescRec 函数设置多个描述符字段，这些字段会影响绑定到列或参数数据的数据类型和缓冲区。
语法
SQLRETURN SQLSetDescRec(
SQLHDESC DescriptorHandle,
SQLSMALLINT RecNumber,
SQLSMALLINT Type,
SQLSMALLINT SubType,
SQLLEN Length,
SQLSMALLINT Precision,
SQLSMALLINT Scale,
SQLPOINTER DataPtr,
SQLLEN * StringLengthPtr,
SQLLEN * IndicatorPtr);
参数
DescriptorHandle
[输入]描述符句柄。 这不能是 IRD 句柄。
RecNumber
[输入]指示包含要设置的字段的描述符记录。 描述符记录从 0 开始编号，记录号 0 为书签记录。 此参数必须等于或大于 0。 如果 RecNumber 大于 SQL_DESC_COUNT 的值，SQL_DESC_COUNTis更改为 RecNumber 的值。
类型
[输入]要设置描述符记录SQL_DESC_TYPE字段的值。
子类型
[输入]对于类型为 SQL_DATETIME 或 SQL_INTERVAL 的记录，这是要设置SQL_DESC_DATETIME_INTERVAL_CODE字段的值。
长度
[输入]要设置描述符记录SQL_DESC_OCTET_LENGTH字段的值。
精度
[输入]要设置描述符记录SQL_DESC_PRECISION字段的值。
缩放
[输入]要设置描述符记录SQL_DESC_SCALE字段的值。
DataPtr
[延迟的输入或输出]要设置描述符记录SQL_DESC_DATA_PTR字段的值。 DataPtr 可以设置为 null 指针。
可以将 DataPtr 参数设置为 null 指针，以将SQL_DESC_DATA_PTR字段设置为 null 指针。 如果 DescriptorHandle 参数中的句柄与 ARD 关联，则取消绑定列。
StringLengthPtr
[延迟的输入或输出]要设置描述符记录SQL_DESC_OCTET_LENGTH_PTR字段的值。 StringLengthPtr 可以设置为 null 指针，以将SQL_DESC_OCTET_LENGTH_PTR字段设置为 null 指针。
IndicatorPtr
[延迟的输入或输出]要设置描述符记录SQL_DESC_INDICATOR_PTR字段的值。 可以将 IndicatorPtr 设置为 null 指针，以将SQL_DESC_INDICATOR_PTR字段设置为 null 指针。
返回
SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或 SQL_INVALID_HANDLE。
诊断
当 SQLSetDescRec 返回SQL_ERROR或SQL_SUCCESS_WITH_INFO时，可以通过调用 SQLGetDiagRec 和 Handle 为 SQL_HANDLE_DESC 和 Handle ofDescriptorHandle 来获取关联的 SQLSTATE 值。 下表列出了 SQLSetDescRec 通常返回的 SQLSTATE 值，并说明了此函数上下文中的每个值;表示法“ (DM) ”位于驱动程序管理器返回的 SQLSTATEs 说明之前。 与每个 SQLSTATE 值关联的返回代码SQL_ERROR，除非另有说明。
| SQLSTATE | 错误 | 说明 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.) |
| 07009 | 描述符索引无效 | RecNumber 参数设置为 0，并且 DescriptorHandle 引用了 IPD 句柄。 RecNumber 参数小于 0。 RecNumber 参数大于数据源可以支持的最大列数或参数数，并且 DescriptorHandle 参数是 APD、IPD 或 ARD。 RecNumber 参数等于 0，而 DescriptorHandle 参数引用隐式分配的 APD。 (显式分配的应用程序描述符不会发生此错误，因为直到执行 time.) |
| 08S01 | 通信链接失败 | 在函数完成处理之前，驱动程序与驱动程序连接到的数据源之间的通信链接失败。 |
| HY000 | 常规错误 | 发生错误，其中没有特定的 SQLSTATE，并且没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | (DM) DescriptorHandle 与 一个 StatementHandle 相关联，该语句调用了异步执行的函数 (不是此) 函数，并且调用此函数时仍在执行。 (DM) SQLExecute、 SQLExecDirect、 SQLBulkOperations 或 SQLSetPos 被调用，该 语句 与 DescriptorHandle 关联并返回SQL_NEED_DATA。 在为所有数据执行时参数或列发送数据之前调用了此函数。 (DM) 为与 DescriptorHandle 关联的连接句柄调用了异步执行的函数。 调用 SQLSetDescRec 函数时，此异步函数仍在执行。 (DM) SQLExecute、 SQLExecDirect 或 SQLMoreResults 已为 与 DescriptorHandle 关联的语句句柄之一调用，并返回SQL_PARAM_DATA_AVAILABLE。 此函数是在检索所有流式处理参数的数据之前调用的。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为无法访问基础内存对象，可能是因为内存不足。 |
| HY016 | 无法修改实现行描述符 | DescriptorHandle 参数与 IRD 相关联。 |
| HY021 | 描述符信息不一致 | 类型字段或描述符中与SQL_DESC_TYPE字段关联的任何其他字段无效或一致。 在一致性检查期间检查的描述符信息不一致。 (请参阅本节后面的“一致性检查”。) |
| HY090 | 无效的字符串或缓冲区长度 | (DM) 驱动程序是 ODBC 2.x 驱动程序，描述符是 ARD， ColumnNumber 参数设置为 0，为参数 BufferLength 指定的值不等于 4。 |
| HY117 | 由于未知的事务状态，连接已挂起。 仅允许断开连接和只读函数。 | (DM) 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 超过连接超时时间 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 SQLSetConnectAttr SQL_ATTR_CONNECTION_TIMEOUT设置的。 |
| IM001 | 驱动程序不支持此函数 | (DM) 与 DescriptorHandle 关联的驱动程序不支持函数。 |
注释
应用程序可以调用 SQLSetDescRec 来为单个列或参数设置以下字段：
SQL_DESC_TYPE
类型为SQL_DATETIME或SQL_INTERVAL) 的记录的SQL_DESC_DATETIME_INTERVAL_CODE (
SQL_DESC_OCTET_LENGTH
SQL_DESC_PRECISION
SQL_DESC_SCALE
SQL_DESC_DATA_PTR
SQL_DESC_OCTET_LENGTH_PTR
SQL_DESC_INDICATOR_PTR
注意
如果对 SQLSetDescRec 的调用失败，则由 RecNumber 参数标识的描述符记录的内容未定义。
绑定列或参数时， SQLSetDescRec 允许更改影响绑定的多个字段，而无需调用 SQLBindCol 或 SQLBindParameter 或多次调用 SQLSetDescField。 SQLSetDescRec 可以在当前未与语句关联的描述符上设置字段。 请注意， SQLBindParameter 设置比 SQLSetDescRec 更多的字段，可以在一次调用中同时设置 APD 和 IPD 上的字段，并且不需要描述符句柄。
注意
在调用 SQLSetDescRec 之前，应始终设置 SQL_ATTR_USE_BOOKMARKS 语句属性，其 RecNumber 参数为 0 以设置书签字段。 虽然这不是强制性的，但强烈建议这样做。
一致性检查
每当应用程序设置 APD、ARD 或 IPD 的SQL_DESC_DATA_PTR字段时，驱动程序都会自动执行一致性检查。 如果任何字段与其他字段不一致， SQLSetDescRec 将返回 SQLSTATE HY021 (描述符信息不一致) 。
每当应用程序设置 APD、ARD 或 IPD 的SQL_DESC_DATA_PTR字段时，驱动程序都会检查SQL_DESC_TYPE字段的值以及适用于该SQL_DESC_TYPE字段的值是否有效且一致。 当调用 SQLBindParameter 或 SQLBindCol 或为 APD、ARD 或 IPD 调用 SQLSetDDescRec 时，始终执行此检查。 此一致性检查包括对描述符字段的以下检查：
SQL_DESC_TYPE字段必须是有效的 ODBC C 或 SQL 类型之一或特定于驱动程序的 SQL 类型之一。 SQL_DESC_CONCISE_TYPE字段必须是有效的 ODBC C 或 SQL 类型之一，或者特定于驱动程序的 C 或 SQL 类型之一，包括简洁的日期时间和间隔类型。
如果SQL_DESC_TYPE记录字段SQL_DATETIME或SQL_INTERVAL，则SQL_DESC_DATETIME_INTERVAL_CODE字段必须是有效的日期/时间或间隔代码之一。 (请参阅 SQLSetDescField.) 中SQL_DESC_DATETIME_INTERVAL_CODE字段的说明
如果SQL_DESC_TYPE字段指示数值类型，则验证SQL_DESC_PRECISION和SQL_DESC_SCALE字段是否有效。
如果SQL_DESC_CONCISE_TYPE字段是时间或时间戳数据类型、具有秒分量的间隔类型或具有时间分量的间隔数据类型之一，则将SQL_DESC_PRECISION字段验证为有效的秒精度。
如果SQL_DESC_CONCISE_TYPE为间隔数据类型，则会验证SQL_DESC_DATETIME_INTERVAL_PRECISION字段是否为有效的间隔前导精度值。
通常不设置 IPD 的SQL_DESC_DATA_PTR字段;但是，应用程序可以这样做来强制对 IPD 字段进行一致性检查。 无法对 IRD 执行一致性检查。 IPD 的 SQL_DESC_DATA_PTR 字段设置为 的值实际上未存储，并且无法通过调用 SQLGetDescField 或 SQLGetDescRec 检索;设置只是为了强制进行一致性检查。
相关函数
| 有关以下方面的信息 | 请参阅 |
|---|---|
| 绑定列 | SQLBindCol 函数 |
| 绑定参数 | SQLBindParameter 函数 |
| 获取单个描述符字段 | SQLGetDescField 函数 |
| 获取多个描述符字段 | SQLGetDescRec 函数 |
| 设置单个描述符字段 | SQLSetDescField 函数 |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈