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);
参数
描述符Handle
[输入]描述符句柄。 这不能是 IRD 句柄。
RecNumber
[输入]指示包含要设置的字段的描述符记录。 描述符记录从 0 编号，记录号 0 是书签记录。 此参数必须等于或大于 0。 如果 RecNumber 大于 SQL_DESC_COUNT 的值，SQL_DESC_COUNTis 更改为 recNumber的值。
类型
[输入]要为其设置描述符记录的SQL_DESC_TYPE字段的值。
SubType
[输入]对于类型为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 来获取关联的 SQLSTATE 值，HandleType 为 SQL_HANDLE_DESC，HandleDescriptorHandle。 下表列出了 SQLSetDescRec 通常返回的 SQLSTATE 值，并解释此函数上下文中的每个值;表示法“（DM）”位于驱动程序管理器返回的 SQLSTATE 的说明之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。
| SQLSTATE | 错误 | 描述 |
|---|---|---|
| 01000 | 常规警告 | 特定于驱动程序的信息性消息。 （函数返回SQL_SUCCESS_WITH_INFO。） |
| 07009 | 描述符索引无效 |
RecNumber 参数设置为 0，描述符Handle 引用 IPD 句柄。 RecNumber 参数小于 0。 RecNumber 参数大于数据源可以支持的最大列数或参数数，描述符Handle 参数是 APD、IPD 或 ARD。 RecNumber 参数等于 0，描述符Handle 参数引用了隐式分配的 APD。 （显式分配的应用程序描述符不会发生此错误，因为它不知道显式分配的应用程序描述符是 APD 还是 ARD，直到执行时间。 |
| 08S01 | 通信链接失败 | 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。 |
| HY000 | 常规错误 | 发生错误：没有特定的 SQLSTATE，也没有定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述了错误及其原因。 |
| HY001 | 内存分配错误 | 驱动程序无法分配支持执行或完成函数所需的内存。 |
| HY010 | 函数序列错误 | （DM） 描述符Handle 与 StatementHandle 相关联，其中调用了异步执行函数（而不是此函数），并在调用此函数时仍在执行。 （DM） SQLExecute、SQLExecDirect、SQLBulkOperations，或 SQLSetPos 调用 StatementHandle，描述符Handle 关联并返回SQL_NEED_DATA。 在为所有数据执行参数或列发送数据之前调用此函数。 （DM） 为与 描述符Handle关联的连接句柄调用异步执行函数。 调用 SQLSetDescRec 函数时，此异步函数仍在执行。 （DM） SQLExecute、SQLExecDirect或 SQLMoreResults 调用了与 描述符Handle 关联的语句句柄之一并返回SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。 |
| HY013 | 内存管理错误 | 无法处理函数调用，因为基础内存对象无法访问，可能是因为内存条件低。 |
| HY016 | 无法修改实现行描述符 | 描述符Handle 参数与 IRD 相关联。 |
| HY021 | 不一致的描述符信息 |
类型 字段或描述符中与SQL_DESC_TYPE字段关联的任何其他字段无效或一致。 在一致性检查期间检查的描述符信息不一致。 （请参阅本节后面的“一致性检查”。 |
| HY090 | 字符串或缓冲区长度无效 | （DM） 驱动程序是 ODBC 2.x 驱动程序，描述符为 ARD，ColumnNumber 参数设置为 0，并且为参数指定的值 BufferLength 不等于 4。 |
| HY117 | 连接因未知事务状态而挂起。 仅允许断开连接和只读函数。 | （DM） 有关挂起状态的详细信息，请参阅 SQLEndTran 函数。 |
| HYT01 | 连接超时已过期 | 在数据源响应请求之前，连接超时期限已过期。 连接超时期限是通过 sqlSetConnectAttr |
| IM001 | 驱动程序不支持此函数 | （DM） 与 描述符Handle 关联的驱动程序不支持该函数。 |
评论
应用程序可以调用 SQLSetDescRec，为单个列或参数设置以下字段：
SQL_DESC_TYPE
SQL_DESC_DATETIME_INTERVAL_CODE（对于类型为SQL_DATETIME或SQL_INTERVAL的记录）
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字段的值是否有效且一致。 调用 SQLBindCol 或 SQLBindCol 时，或者为 APD、ARD 或 IPD 调用 SQLSetDescrec 时，始终执行此检查。 此一致性检查包括对描述符字段的以下检查：
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 函数 |