SQLSetDescField 函数

一致性
推出版本：ODBC 3.0 标准合规：ISO 92

总结
SQLSetDescField 是描述符记录中单个字段的值。

Syntax

SQLRETURN SQLSetDescField(  
     SQLHDESC      DescriptorHandle,  
     SQLSMALLINT   RecNumber,  
     SQLSMALLINT   FieldIdentifier,  
     SQLPOINTER    ValuePtr,  
     SQLINTEGER    BufferLength);  

Arguments

DescriptorHandle
[输入]描述符的使用。

RecNumber
[输入]表示包含应用程序欲设置字段的描述符记录。 描述符记录从0开始编号，记录编号0为书签记录。 RecNumber 参数在首部字段中被忽略。

FieldIdentifier
[输入]表示要设定值的描述符字段。 更多信息请参见“评论”部分的“字段标识 符参数”。

ValuePtr
[输入]指向包含描述符信息或整数值的缓冲区。 数据类型取决于 字段标识符的值。 如果 ValuePtr 是一个整数值，则根据 FieldIdentifier 参数的值，它可以被视为 8 字节（SQLLEN）、4 字节（SQLINTEGER）或 2 字节（SQLSMALLINT）。

BufferLength
[输入]如果 FieldIdentifier 是 ODBC 定义的字段，且 ValuePtr 指向一个字符串或二进制缓冲区，那么该参数应为 *ValuePtr 的长度。 对于字符字符串数据，该参数应包含字符串中的字节数。

如果 字段标识 符是ODBC定义的字段，且 ValuePtr 是整数字段，则忽略 缓冲长度 。

如果 FieldIdentifier 是驱动程序定义的字段，应用程序通过设置 BufferLength 参数向驱动程序管理器指示字段的性质。 缓冲长度 可以有以下数值：

• 如果 ValuePtr 是指向字符字符串的指针，那么 BufferLength 就是该字符串或 SQL_NTS 的长度。

• 如果 ValuePtr 是指向二进制缓冲区的指针，应用程序会将 SQL_LEN_BINARY_ATTR（length） 宏的结果置入 BufferLength。 这会使 缓冲长度为负值。

• 如果 ValuePtr 指向非字符字符串或二进制字符串的值，那么 BufferLength 应具有 SQL_IS_POINTER 值。

• 如果 ValuePtr 包含固定长度值，则 BufferLength 可以是 SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT 或 SQL_IS_USMALLINT，视情况而定。

Returns

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR 或SQL_INVALID_HANDLE。

Diagnostics

当 SQLSetDescField 返回 SQL_ERROR 或 SQL_SUCCESS_WITH_INFO 时，可以通过调用 SQLGetDiagRec 获得关联的 SQLSTATE 值， Handle 为 SQL_HANDLE_DESC，Handle 为 DescriptorHandle 。 下表列出 了SQLSetDescField 通常返回的SQLSTATE值，并在此函数的上下文中对每个值进行了解释;“（DM）” 符号位于驱动程序管理器返回的 SQLSTATE 描述之前。 除非另有说明，否则与每个 SQLSTATE 值关联的返回代码SQL_ERROR。

注释

应用程序可以调用 SQLSetDescField ，一次只设置任意描述符字段。 调用 SQLSetDescField 时，将单个字段映射到单一描述符中。 该函数可以调用来设置任意描述符类型的任意字段，前提是该字段可以被设置。 （详见本节后表。）

其他函数也可以调用，通过一次调用该函数来设置多个描述字段。 SQLSetDescRec 函数设置了多种字段，影响列或参数绑定的数据类型和缓冲区（SQL_DESC_TYPE、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 字段）。 SQLBindCol 或 SQLBindParameter 可用于为列或参数的绑定制定完整的规范。 这些函数通过一次函数调用来设置特定的描述符字段组。

可以通过在绑定指针（SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR或SQL_DESC_OCTET_LENGTH_PTR）上添加偏移量来调用SQLSetDescField来更改绑定缓冲区。 这在不调用 SQLBindCol 或 SQLBindParameter 的情况下更改绑定缓冲区，使应用程序能够在不更改其他字段（如 SQL_DESC_DATA_TYPE）的情况下更改SQL_DESC_DATA_PTR。

如果应用程序调用 SQLSetDescField 设置除 SQL_DESC_COUNT 或延迟字段SQL_DESC_DATA_PTR、SQL_DESC_OCTET_LENGTH_PTR 或 SQL_DESC_INDICATOR_PTR 以外的任何字段，该记录将解除绑定。

描述符头字段通过调用带有相应字段标识符的 SQLSetDescField 来设置。 许多头字段也是语句属性，因此也可以通过调用 SQLSetStmtattr 来设置。 这使得应用程序可以在不先获得描述符句柄的情况下设置描述符字段。 当调用 SQLSetDescField 设置报头字段时， RecNumber 参数会被忽略。

RecNumber 为 0 用于设置书签字段。

描述符字段的序列

当通过调用 SQLSetDescField 设置描述符字段时，应用程序必须遵循特定的序列：

1. 应用程序必须先设置SQL_DESC_TYPE、SQL_DESC_CONCISE_TYPE或SQL_DESC_DATETIME_INTERVAL_CODE字段。

2. 设置完其中一个字段后，应用程序可以设置数据类型的属性，驱动程序将数据类型属性字段设置为该数据类型的适当默认值。 类型属性字段自动默认，确保描述符在应用程序指定数据类型后始终可用。 如果应用程序显式设置了数据类型属性，它就是覆盖默认属性。

3. 在设置了步骤1中列出的字段之一，并且设置了数据类型属性后，应用程序可以设置SQL_DESC_DATA_PTR。 这会促使描述符字段进行一致性检查。 如果应用程序在设置SQL_DESC_DATA_PTR字段后更改了数据类型或属性，驱动程序会将SQL_DESC_DATA_PTR设置为空指针，解绑记录。 这迫使应用程序按顺序完成正确的步骤，描述符记录才可用。

描述符字段的初始化

当描述符被分配时，描述符中的字段可以初始化为默认值，也可以在没有默认值的情况下初始化，或者对描述符类型保持未定义。 下表显示了每种描述符类型对每个字段的初始化，其中“D”表示该字段初始化时带有默认值，“ND”表示字段初始化时没有默认值。 如果显示一个数字，该字段的默认值即为该数字。 表格还指示字段是读写（R/W）还是只读（R）。

IRD字段的默认值仅在语句准备或执行且IRD填充后才有，而在语句句柄或描述符被分配后则不存在。 在IRD填充之前，任何试图访问IRD字段的尝试都会返回错误。

部分描述符字段为一种或多种描述符类型（ARD和IRD，APD和IPD）定义，但并非全部。 当某个字段对某种描述符类型未定义时，使用该描述符的任何函数都不需要该字段。

SQLGetDescField 可访问的字段不一定能由 SQLSetDescField 设置。 SQLSetDescField 可设置的字段列于下表。

头字段的初始化方法详见下表。

[1] 这些字段仅在驾驶员自动填充IPD时定义。 否则，它们未定义。 如果应用程序尝试设置这些字段，将返回 SQLSTATE HY091（描述符字段标识符无效）。

记录字段的初始化如下表所示。

[1] 这些字段仅在驾驶员自动填充IPD时定义。 否则，它们未定义。 如果应用程序尝试设置这些字段，将返回 SQLSTATE HY091（描述符字段标识符无效）。

[2] IPD 中的SQL_DESC_DATA_PTR字段可以设置为强制一致性检查。 在随后调用 SQLGetDescField 或 SQLGetDescRec 时，驱动程序无需返回 SQL_DESC_DATA_PTR 设定的值。

字段标识符参数

FieldIdentifier 参数表示要设置的描述符字段。 描述符包含描述 符头部， 由下一节“头字段”中描述的头字段组成，以及零个或多个 描述符记录， 包含“头字段”节后节描述的记录字段。

头字段

每个描述符有一个由以下字段组成的头部：

SQL_DESC_ALLOC_TYPE [全体]
该只读 SQLSMALLINT 头字段指定描述符是驱动程序自动分配还是应用程序显式分配。 应用程序可以获取但不能修改该字段。 如果描述符是驱动程序自动分配的，则该字段由驱动程序设置为SQL_DESC_ALLOC_AUTO。 如果描述符是应用程序显式分配的，驱动程序将它设置为SQL_DESC_ALLOC_USER。

SQL_DESC_ARRAY_SIZE [应用描述符]
在ARD中，该SQLULEN头字段指定行集的行数。 这是调用 SQLFetch 或 SQLFetchScroll 或调用 SQLBulkOperations 或 SQLSetPos 操作时返回的行数。

在APD中，这个SQLULEN头字段指定每个参数的值数。

该字段的默认值为1。 如果SQL_DESC_ARRAY_SIZE大于1，APD或ARD的SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR指向阵列。 每个数组的基数等于该场的值。

ARD 中的该字段也可以通过调用带有 SQL_ATTR_ROW_ARRAY_SIZE 属性的 SQLSetStmtAttr 来设置。 APD中的该字段也可以通过调用带有SQL_ATTR_PARAMSET_SIZE属性的 SQLSetStmtAttr 来设置。

SQL_DESC_ARRAY_STATUS_PTR [所有人]
对于每个描述符类型，这个 SQLUSMALLINT * 头字段指向一个 SQLUSMALLINT 数组的值。 这些数组分别命名为：行状态数组（IRD）、参数状态数组（IPD）、行操作数组（ARD）和参数操作数组（APD）。

在IRD中，该头字段指向一个包含调用 SQLBulkOperations、 SQLFetch、 SQLFetchScroll或 SQLSetPos后状态值的行状态数组。 数组的元素数量与行集中的行数相同。 应用程序必须分配一个 SQLUSMALLINT 数组，并将该字段指向该数组。 该字段默认设置为空指针。 驱动程序会填充数组——除非SQL_DESC_ARRAY_STATUS_PTR字段设置为空指针，此时不生成状态值，数组也未被填充。

该数组最初通过调用 SQLBulkOperations、 SQLFetch、 SQLFetchScroll 或 SQLSetPos 填充。 如果调用未返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，则该字段指向的数组内容未定义。 数组中的元素可以包含以下值：

• SQL_ROW_SUCCESS：该行已成功取出，自上次取回以来未曾改变。

• SQL_ROW_SUCCESS_WITH_INFO：该行已成功取回，自上次取出以来未曾更改。 但是，已返回有关该行的警告。

• SQL_ROW_ERROR：取回该行时发生了错误。

• SQL_ROW_UPDATED：该行已成功获取，自上次获取以来已持续更新。 如果再次取回该行，其状态为SQL_ROW_SUCCESS。

• SQL_ROW_DELETED：该行自上次取入后已被删除。

• SQL_ROW_ADDED：该行由 SQLBulkOperations 插入。 如果再次取回该行，其状态为SQL_ROW_SUCCESS。

• SQL_ROW_NOROW：行集与结果集末尾重叠，且没有返回对应该行状态数组元素的行。

IRD 中的该字段也可以通过调用带有 SQL_ATTR_ROW_STATUS_PTR 属性的 SQLSetStmtAttr 来设置。

IRD的SQL_DESC_ARRAY_STATUS_PTR字段仅在SQL_SUCCESS或返回SQL_SUCCESS_WITH_INFO后有效。 如果返回码不是这些，SQL_DESC_ROWS_PROCESSED_PTR指向的位置未定义。

在IPD中，该头字段指向一个参数状态数组，包含调用 SQLExecute 或 SQLExecDirect后每个参数值集合的状态信息。 如果调用 SQLExecute 或 SQLExecDirect 未返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，则该字段指向的数组内容未定义。 应用程序必须分配一个 SQLUSMALLINT 数组，并将该字段指向该数组。 驱动程序会填充数组——除非SQL_DESC_ARRAY_STATUS_PTR字段设置为空指针，此时不生成状态值，数组也未被填充。 数组中的元素可以包含以下值：

• SQL_PARAM_SUCCESS：SQL语句已成功执行该参数集。

• SQL_PARAM_SUCCESS_WITH_INFO：SQL语句已成功执行该参数集;然而，诊断数据结构中提供了警告信息。

• SQL_PARAM_ERROR：处理这组参数时发生了错误。 诊断数据结构中提供了额外的错误信息。

• SQL_PARAM_UNUSED：该参数集未被使用，可能是因为之前的某些参数集导致错误导致后续处理中止，或是该参数集在APD的SQL_DESC_ARRAY_STATUS_PTR字段指定数组中被设置SQL_PARAM_IGNORE。

• SQL_PARAM_DIAG_UNAVAILABLE：诊断信息不可得。 例如，当驱动程序将参数数组视为单体单元，因此不产生这种级别的错误信息时。

IPD 中的该字段也可以通过调用带有 SQL_ATTR_PARAM_STATUS_PTR 属性的 SQLSetStmtAttr 来设置。

在ARD中，该头字段指向一个行操作数组，应用程序可以设置该数组，指示该行是否应被忽略用于 SQLSetPos 操作。 数组中的元素可以包含以下值：

• SQL_ROW_PROCEED：该行包含在使用 SQLSetPOS 的批量操作中。 （此设置并不保证操作会在该行上执行。如果该行在IRD行状态数组中有状态SQL_ROW_ERROR，驱动程序可能无法在该行执行该操作。）

• SQL_ROW_IGNORE：该行通过 SQLSetPos 排除在批量操作之外。

如果数组中没有元素被设置，所有行都包含在批量操作中。 如果ARD SQL_DESC_ARRAY_STATUS_PTR字段中的值是空指针，所有行都包含在bulk操作中;解释方式与指针指向有效数组且所有元素均为SQL_ROW_PROCEED相同。 如果数组中的元素设置为SQL_ROW_IGNORE，忽略行的状态数组中的值不会改变。

ARD 中的该字段也可以通过调用带有 SQL_ATTR_ROW_OPERATION_PTR 属性的 SQLSetStmtAttr 来设置。

在APD中，该头字段指向一个参数操作数组，应用程序可以设置该数组值，指示调用 SQLExecute 或 SQLExecDirect 时是否应忽略该参数集。 数组中的元素可以包含以下值：

• SQL_PARAM_PROCEED：参数集包含在 SQLExecute 或 SQLExecDirect 调用中。

• SQL_PARAM_IGNORE：参数集被排除在 SQLExecute 或 SQLExecDirect 调用之外。

如果数组中没有设置任何元素，则在 SQLExecute 或 SQLExecDirect 调用中使用数组中的所有参数集合。 如果APD SQL_DESC_ARRAY_STATUS_PTR字段中的值是空指针，则使用所有参数集;解释方式与指针指向有效数组且数组中所有元素均为SQL_PARAM_PROCEED相同。

APD中的该字段也可以通过调用带有SQL_ATTR_PARAM_OPERATION_PTR属性的 SQLSetStmtAttr 来设置。

SQL_DESC_BIND_OFFSET_PTR [应用描述符]
这个 SQLLEN * 头字段指向绑定偏移量。 默认情况下，它被设置为空指针。 如果该字段不是空指针，驱动程序会在取指针时取消引用该指针，并在获取时将该去引用值添加到描述符记录中非空值的每个延迟字段（SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR），绑定时使用新的指针值。

绑定偏移总是直接加到SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR字段的值中。 如果偏移量被更改为不同值，新值仍会直接添加到每个描述符字段的值中。 新的偏移量不会加到场值加上任何之前的偏移量上。

该字段为 延迟字段：设置时不使用，驱动在需要确定数据缓冲区地址时使用。

ARD中的该字段也可以通过调用带有SQL_ATTR_ROW_BIND_OFFSET_PTR属性的 SQLSetStmtAttr 来设置。 ARD 中的该字段也可以通过调用带有 SQL_ATTR_PARAM_BIND_OFFSET_PTR 属性的 SQLSetStmtAttr 来设置。

欲了解更多信息，请参阅 SQLFetchScroll 和 SQLBindParameter 中关于行绑定的描述。

SQL_DESC_BIND_TYPE [应用描述符]
该 SQLUINTEGER 头字段设置了用于绑定列或参数的绑定方向。

在ARD中，该字段指定在调用 SQLFetchScroll 或 SQLFetch 时对关联语句句柄的绑定方向。

为了选择列绑定，该字段设置为SQL_BIND_BY_COLUMN（默认值）。

ARD 中的该字段也可以通过调用带有 SQL_ATTR_ROW_BIND_TYPE 属性的 SQLSetStmtAttr 来设置。

在APD中，该字段指定动态参数的绑定方向。

为了选择参数的列绑定，该字段设置为SQL_BIND_BY_COLUMN（默认值）。

APD中的该字段也可以通过调用带有SQL_ATTR_PARAM_BIND_TYPE属性的SQLSetStmtAttr来设置。

SQL_DESC_COUNT [所有人]
该 SQLSMALLINT 头字段指定包含数据的最高编号记录的基于 1 的索引。 当驱动程序设置描述符的数据结构时，还必须设置SQL_DESC_COUNT字段以显示有多少条记录具有重要性。 当应用程序分配该数据结构的实例时，无需指定保留多少记录空间。 当应用程序指定记录内容时，驱动程序会采取必要操作，确保描述符句柄指向足够大小的数据结构。

SQL_DESC_COUNT不是所有被绑定的数据列（如果字段在ARD中）或所有被绑定参数的计数（如果字段在APD），而是最高编号记录的数量。 如果编号最高的列或参数未绑定，则SQL_DESC_COUNT会被更改为下一个编号最高的列或参数的编号。 如果某个列或参数的数字小于最高编号列的编号被解除绑定（通过调用 SQLBindCol 的 TargetValuePtr 参数设置为空指针，或 SQLBindParameter 的参数参数设置为空指针），SQL_DESC_COUNT不会被更改。 如果额外的列或参数被绑定在包含数据的最高记录中大于编号最高的记录，驱动程序会自动增加SQL_DESC_COUNT字段中的值。 如果通过调用 SQLFreeStmt 并启用 SQL_UNBIND 选项，所有列都解除绑定，ARD 和 IRD 中的 SQL_DESC_COUNT 字段都设置为 0。 如果调用 SQLFreeStmt 并选择 SQL_RESET_PARAMS，APD 和 IPD 中的 SQL_DESC_COUNT 字段设置为 0。

应用程序可以通过调用 SQLSetDescField 显式设置 SQL_DESC_COUNT 中的值。 如果SQL_DESC_COUNT中的值被明确减少，所有数字大于SQL_DESC_COUNT新值的记录都会被有效移除。 如果SQL_DESC_COUNT中的值被明确设置为0且字段在ARD中，除绑定书签列外的所有数据缓冲区都会被释放。

ARD该字段的记录计数不包括装订书签列。 解绑书签列的唯一方法是将SQL_DESC_DATA_PTR字段设置为空指针。

SQL_DESC_ROWS_PROCESSED_PTR [实现描述符]
在IRD中，SQLULEN *头字段指向一个缓冲区，该缓冲区包含调用 SQLFetch 或 SQLFetchScroll后获取的行数，或调用 SQLBulkOperations 或 SQLSetPos执行的批量操作中受影响的行数，包括错误行。

在IPD中，这个SQLUINTEGER *头字段指向一个缓冲区，缓冲区包含已处理的参数集数量，包括错误集。 如果这是空指针，则不会返回任何数字。

SQL_DESC_ROWS_PROCESSED_PTR仅在调用 SQLFetch 或 SQLFetchScroll （IRD 字段）、 SQLExecute、 SQLExecDirect 或 SQLParamData （IPD 字段）后返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO 后才有效。 如果填充该字段指向的缓冲区调用未返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，则缓冲区内容未定义，除非返回SQL_NO_DATA，此时缓冲区中的值设为0。

ARD 中的该字段也可以通过调用带有 SQL_ATTR_ROWS_FETCHED_PTR 属性的 SQLSetStmtAttr 来设置。 APD 中的该字段也可以通过调用带有 SQL_ATTR_PARAMS_PROCESSED_PTR 属性的 SQLSetStmtAttr 来设置。

该字段指向的缓冲区由应用程序分配。 它是驱动程序设置的延迟输出缓冲区。 默认情况下，它被设置为空指针。

纪录场

每个描述符包含一个或多个记录，这些字段定义了列数据或动态参数，具体取决于描述符的类型。 每条记录都是对单一列或参数的完整定义。

SQL_DESC_AUTO_UNIQUE_VALUE [IRDS]
如果列是自动递增列，这个只读SQLINTEGER 记录字段包含SQL_TRUE;如果列不是自动递增列，则包含SQL_FALSE。 该字段是只读的，但底层的自动递增列不一定是只读的。

SQL_DESC_BASE_COLUMN_NAME [IRDS]
这个只读的 SQLCHAR * 记录字段包含结果集列的基础列名。 如果不存在基础列名（如表达式列的情况），该变量包含空字符串。

SQL_DESC_BASE_TABLE_NAME [IRD]
这个只读的 SQLCHAR * 记录字段包含结果集列的基表名称。 如果无法定义或不适用基础表名称，该变量包含空字符串。

SQL_DESC_CASE_SENSITIVE [实现描述符]
该只读SQLINTEGER 记录字段包含SQL_TRUE，如果该列或参数在对调和比较时不区分大小写，或为非字符列，则为SQL_FALSE。

SQL_DESC_CATALOG_NAME [IRD]
这个只读的 SQLCHAR * 记录字段包含包含该列的基表的目录。 如果列是表达式或列属于视图，返回值则依赖驱动。 如果数据源不支持目录或无法确定目录，该变量包含空字符串。

SQL_DESC_CONCISE_TYPE [全体]
该SQLSMALLINT头字段指定了所有数据类型的简明数据类型，包括日期时间和区间数据类型。

SQL_DESC_CONCISE_TYPE、SQL_DESC_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE字段中的值相互依赖。 每当一个字段被设置时，另一个字段也必须被设置。 SQL_DESC_CONCISE_TYPE可以通过调用 SQLBindCol 或 SQLBindParameter 或 SQLSetDescField 来设置。 SQL_DESC_TYPE可以通过调用 SQLSetDescField 或 SQLSetDescRec 来设置。

如果SQL_DESC_CONCISE_TYPE设置为非区间或日期时间数据类型的简洁数据类型，SQL_DESC_TYPE字段设置为相同值，SQL_DESC_DATETIME_INTERVAL_CODE字段设置为0。

如果SQL_DESC_CONCISE_TYPE设置为简明的日期时间或区间数据类型，SQL_DESC_TYPE字段设置为对应的冗长类型（SQL_DATETIME或SQL_INTERVAL），SQL_DESC_DATETIME_INTERVAL_CODE字段设置为相应子代码。

SQL_DESC_DATA_PTR [应用描述符和IPD]
该 SQLPOINTER 记录字段指向一个变量，该变量将包含参数值（针对 APD）或列值（针对 ARD）。 该场地为 延迟场地。 它不在设置时使用，而是驱动程序在后续时间用来检索数据。

如果调用 SQLBindCol 中的 TargetValuePtr 参数是空指针，或者 ARD 中的SQL_DESC_DATA_PTR字段是由调用 SQLSetDescField 或 SQLSetDescRec 对空指针设置的，则该SQL_DESC_DATA_PTR列是未绑定的。 如果SQL_DESC_DATA_PTR字段设置为空指针，其他字段不受影响。

如果调用 SQLFetch 或 SQLFetchScroll 填充该字段所指向缓冲区的缓冲区未返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，则缓冲区内容未定义。

每当设置APD、ARD或IPD的SQL_DESC_DATA_PTR字段时，驱动程序会检查SQL_DESC_TYPE字段中的值是否包含有效的ODBC C数据类型或驱动程序特定数据类型，并且所有影响数据类型的字段保持一致。 提示一致性检查是IPD SQL_DESC_DATA_PTR字段的唯一用途。 具体来说，如果应用程序设置了IPD的SQL_DESC_DATA_PTR字段，随后调用该字段的 SQLGetDescField ，它不一定返回其设置的值。 更多信息请参见 SQLSetDescRec 中的“一致性检查”。

SQL_DESC_DATETIME_INTERVAL_CODE [所有人]
该 SQLSMALLINT 记录字段包含特定日期时间或区间数据类型的子代码，当 SQL_DESC_TYPE 字段被SQL_DATETIME或SQL_INTERVAL时。 这对SQL和C数据类型都适用。 该代码由数据类型名称组成，“CODE”被替换为“TYPE”或“C_TYPE”（用于日期时间类型），或将“CODE”替换为“INTERVAL”或“C_INTERVAL”（用于区间类型）。

如果应用描述符中的SQL_DESC_TYPE和SQL_DESC_CONCISE_TYPE设置为SQL_C_DEFAULT且描述符未关联语句句柄，则SQL_DESC_DATETIME_INTERVAL_CODE的内容未定义。

该字段可为下表中列出的日期时间数据类型设置。

该字段可以为下表中列出的区间数据类型设置。

有关数据区间和该字段的更多信息，请参见 数据类型标识符和描述符。

SQL_DESC_DATETIME_INTERVAL_PRECISION [全体]
如果SQL_DESC_TYPE字段SQL_INTERVAL，该SQLINTEGER 记录字段包含区间前导精度。 当SQL_DESC_DATETIME_INTERVAL_CODE字段设置为区间数据类型时，该字段被设置为默认的区间前置精度。

SQL_DESC_DISPLAY_SIZE [IRD]
这个只读的SQLINTEGER 记录字段包含显示该列数据所需的最大字符数。

SQL_DESC_FIXED_PREC_SCALE [实现描述符]
如果列是精确数值列且具有固定精度和非零刻度，则该只读SQLSMALLINT记录字段设置为SQL_TRUE;如果列不是精确数值列且具有固定精度和刻度，则设为SQL_FALSE。

SQL_DESC_INDICATOR_PTR [应用描述符]
在ARD中，SQLLEN * 记录字段指向指示变量。 如果列值为NULL，该变量包含SQL_NULL_DATA。 对于APD，指示变量设置为SQL_NULL_DATA以指定NULL动态参数。 否则，变量为零（除非SQL_DESC_INDICATOR_PTR和SQL_DESC_OCTET_LENGTH_PTR中的值是相同的指针）。

如果ARD中的SQL_DESC_INDICATOR_PTR字段是空指针，驱动将无法返回该列是否为NULL的信息。 如果列为 NULL，SQL_DESC_INDICATOR_PTR 为空指针，驱动程序在调用 SQLFetch 或 SQLFetchScroll 后尝试填充缓冲区时，会返回 SQLSTATE 22002（指示变量 required但未提供）。 如果调用 SQLFetch 或 SQLFetchScroll 未返回 SQL_SUCCESS 或 SQL_SUCCESS_WITH_INFO，缓冲区内容未定义。

SQL_DESC_INDICATOR_PTR场决定SQL_DESC_OCTET_LENGTH_PTR所指向的场是否被设定。 如果某列的数据值为 NULL，驱动将指示变量设置为 SQL_NULL_DATA。 SQL_DESC_OCTET_LENGTH_PTR所指向的场则不再被设定。 如果在取指过程中未遇到NULL值，SQL_DESC_INDICATOR_PTR指向的缓冲区设为零，SQL_DESC_OCTET_LENGTH_PTR指向的缓冲区设置为数据长度。

如果APD中的SQL_DESC_INDICATOR_PTR字段是空指针，应用程序不能使用该描述符记录来指定NULL参数。

该字段为 延迟字段：设置时不使用，但驱动程序后续用于表示可空性（ARDs）或确定可空性（APD）。

SQL_DESC_LABEL [IRDS]
这个只读的 SQLCHAR * 记录字段包含列标签或标题。 如果列没有标签，该变量包含列名。 如果列未命名且无标签，该变量包含空字符串。

SQL_DESC_LENGTH [所有人]
该 SQLULEN 记录字段是字符字符串的最大或实际长度（字符数）或二进制数据类型（字节数）。 它是固定长度数据类型的最大长度，或可变长度数据类型的实际长度。 它的值总是排除结尾字符串的空终止字符。 对于类型为SQL_TYPE_DATE、SQL_TYPE_TIME、SQL_TYPE_TIMESTAMP或SQL区间数据类型之一的值，该字段的长度为datetime或区间值的字符字符串表示。

该字段中的值可能与ODBC 2*.x*中定义的“长度”值不同。 更多信息请参见 附录D：数据类型。

SQL_DESC_LITERAL_PREFIX [IRDs]
这个只读的 SQLCHAR * 记录字段包含驱动程序识别为该数据类型文字前缀的字符或字符。 该变量包含一个空字符串，代表一个不适用文字前缀的数据类型。

SQL_DESC_LITERAL_SUFFIX [IRDS]
这个只读的 SQLCHAR * 记录字段包含驱动程序识别为该数据类型文字后缀的字符或字符。 该变量包含一个空字符串，代表一个数据类型，该类型不适用文字后缀。

SQL_DESC_LOCAL_TYPE_NAME [实现描述符]
该只读的 SQLCHAR * 记录字段包含任何本地化（本地语言）数据类型名称，且可能与该数据类型的常规名称不同。 如果没有本地化名称，则返回一个空字符串。 此字段仅供展示用途。

SQL_DESC_NAME [实现描述符]
行描述符中的 SQLCHAR * 记录字段包含列别名（如果适用）。 如果列别名不适用，则返回列名。 无论哪种情况，驱动在设置SQL_DESC_NAME场时将SQL_DESC_UNNAMED场设为SQL_NAMED。 如果没有列名或列别名，驱动会返回SQL_DESC_NAME字段中的空字符串，并将SQL_DESC_UNNAMED字段设置为SQL_UNNAMED。

应用程序可以将IPD的SQL_DESC_NAME字段设置为参数名或别名，以指定存储过程的参数名称。 （更多信息请参见按 名称绑定参数（命名参数）。） IRD的SQL_DESC_NAME字段是只读字段;如果应用程序尝试设置 SQLSTATE HY091（描述符字段标识符无效）将返回该标识符。

在IPD中，如果驱动程序不支持命名参数，该字段是未定义的。 如果驱动程序支持命名参数并能够描述参数，则该字段中返回参数名称。

SQL_DESC_NULLABLE [实现描述符]
在IRD中，如果列可以有NULL值，SQL_NO_NULLS列没有NULL值，SQL_NULLABLE_UNKNOWN则，如果列可以有NULL值，则该记录字段SQL_NULLABLE。 该字段涉及结果集列，而非基础列。

在IPD中，该字段总是设置为SQL_NULLABLE，因为动态参数总是可空的，应用程序无法设置。

SQL_DESC_NUM_PREC_RADIX [全体]
如果SQL_DESC_TYPE字段中的数据类型是近似数值数据类型，则该SQLINTEGER字段的值为2，因为SQL_DESC_PRECISION字段包含位数。 如果SQL_DESC_TYPE字段中的数据类型是精确数字数据类型，则该字段包含10，因为SQL_DESC_PRECISION字段包含十进制数字。 对于所有非数字数据类型，该字段设置为0。

SQL_DESC_OCTET_LENGTH [所有人]
该 SQLLEN 记录字段包含字符字符串或二进制数据类型的长度（字节单位）。 对于固定长度字符或二进制类型，这是实际的字节长度。 对于可变长度字符或二进制类型，这是最大字节长度。 该值始终排除实现描述符的空终止字符空间，并且始终包含应用描述符的空终止字符空间。 对于应用数据，该字段包含缓冲区的大小。 对于APD，该字段仅定义输出或输入输出参数。

SQL_DESC_OCTET_LENGTH_PTR [应用描述符]
这个 SQLLEN * 记录字段指向一个变量，该变量将包含动态参数（参数描述符）的总字节长度，或绑定列值（行描述符）的总长度。

对于APD，除了字符字符串和二进制参数外，该值被忽略;如果该字段指向SQL_NTS，则动态参数必须是空终止的。 为了表示绑定参数为执行时数据参数，应用程序在APD的相应记录中将该字段设为变量，执行时该字段将包含SQL_DATA_AT_EXEC值或SQL_LEN_DATA_AT_EXEC宏的结果。 如果有多个此类字段，SQL_DESC_DATA_PTR可以设置为唯一标识该参数的值，帮助应用程序确定所请求的参数。

如果ARD的OCTET_LENGTH_PTR字段是空指针，驱动子不会返回该列的长度信息。 如果APD的SQL_DESC_OCTET_LENGTH_PTR字段是空指针，驱动程序假设字符字符串和二进制值是空终止的。 （二进制值不应为空终止，但应赋予长度以避免截断。）

如果调用 SQLFetch 或 SQLFetchScroll 填充该字段所指向缓冲区的缓冲区未返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO，则缓冲区内容未定义。 该场地为 延迟场地。 它在设置时不使用，而是驱动程序在后续时间用来确定或指示数据的八位元组长度。

SQL_DESC_PARAMETER_TYPE [瞳距]
该 SQLSMALLINT 记录字段设置为输入参数为 SQL_PARAM_INPUT，输入/输出参数为 SQL_PARAM_INPUT_OUTPUT，输出参数为 SQL_PARAM_OUTPUT，输入/输出流式参数为 SQL_PARAM_INPUT_OUTPUT_STREAM，输出流式参数为 SQL_PARAM_OUTPUT_STREAM。 默认设置为SQL_PARAM_INPUT。

对于IPD，如果IPD未被驱动程序自动填充，该字段默认设置为SQL_PARAM_INPUT（SQL_ATTR_ENABLE_AUTO_IPD语句属性为SQL_FALSE）。 应用程序应在IPD中为非输入参数设置该字段。

SQL_DESC_PRECISION [众人]
该 SQLSMALLINT 记录字段包含精确数字类型的数字数、近似数字类型的尾数（二进制精度）或 SQL_TYPE_TIME、SQL_TYPE_TIMESTAMP 或 SQL_INTERVAL_SECOND 数据类型的分数秒部分中的数字数。 该字段对所有其他数据类型均未定义。

该字段中的值可能与ODBC 2*.x*中定义的“精度”值不同。 更多信息请参见 附录D：数据类型。

SQL_DESC_ROWVER [实现描述符]
该 SQLSMALLINTrecord 字段表示当 DBMS 更新行时（例如，SQL Server 中类型为“timestamp”的列）是否会自动修改该列。 如果该记录字段是行版本控制列，则该字段的值设为SQL_TRUE，否则SQL_FALSE。 该列属性类似于调用带有 IdentifierType 的 SQLSpecialColumns SQL_ROWVER以判断列是否自动更新。

SQL_DESC_SCALE [众人]
该 SQLSMALLINT 记录字段包含定义的十进制和数字数据类型的刻度。 该字段对所有其他数据类型均未定义。

该字段中的值可能与ODBC 2*.x*中定义的“scale”值不同。 更多信息请参见 附录D：数据类型。

SQL_DESC_SCHEMA_NAME [IRDS]
这个只读的 SQLCHAR * 记录字段包含包含该列的基表的模式名称。 如果列是表达式或列属于视图，返回值则依赖驱动。 如果数据源不支持模式或无法确定模式名称，该变量包含空字符串。

SQL_DESC_SEARCHABLE [IRD]
这个只读的 SQLSMALLINT 记录字段设置为以下值之一：

• SQL_PRED_NONE 如果该列不能用于 WHERE 子句。 （这与ODBC 2*.x*中的SQL_UNSEARCHABLE值相同。）

• SQL_PRED_CHAR该列是否可以在 WHERE 子句中使用，但只能与 LIKE 谓词一起使用。 （这与ODBC 2*.x*中的SQL_LIKE_ONLY值相同。）

• SQL_PRED_BASIC 该列是否可以在包含除 LIKE 外所有比较操作符的 WHERE 子句中使用。 （这与ODBC 2*.x*中的SQL_EXCEPT_LIKE值相同。）

• SQL_PRED_SEARCHABLE该列是否可以作为带有任意比较操作符的 WHERE 子句中使用。

SQL_DESC_TABLE_NAME [IRDS]
这个只读的 SQLCHAR * 记录字段包含包含该列的基表名称。 如果列是表达式或列属于视图，返回值则依赖驱动。

SQL_DESC_TYPE [所有人]
该 SQLSMALLINT 记录字段指定了除日期、时间和区间数据类型外的所有数据类型的简明 SQL 或 C 数据类型。 对于日期时间和区间数据类型，该字段指定冗长数据类型，即SQL_DATETIME或SQL_INTERVAL。

每当该字段包含SQL_DATETIME或 SQL_INTERVAL，SQL_DESC_DATETIME_INTERVAL_CODE 字段必须包含该简明类型所需的相应子代码。 对于日期时间数据类型，SQL_DESC_TYPE包含SQL_DATETIME，SQL_DESC_DATETIME_INTERVAL_CODE字段包含特定日期时间数据类型的子代码。 对于区间数据类型，SQL_DESC_TYPE包含SQL_INTERVAL，SQL_DESC_DATETIME_INTERVAL_CODE字段包含特定区间数据类型的子代码。

SQL_DESC_TYPE和SQL_DESC_CONCISE_TYPE字段中的值是相互依赖的。 每当一个字段被设置时，另一个字段也必须被设置。 SQL_DESC_TYPE可以通过调用 SQLSetDescField 或 SQLSetDescRec 来设置。 SQL_DESC_CONCISE_TYPE可以通过调用 SQLBindCol 或 SQLBindParameter 或 SQLSetDescField 来设置。

如果SQL_DESC_TYPE设置为非区间或日期时间数据类型的简洁数据类型，SQL_DESC_CONCISE_TYPE字段设置为相同值，SQL_DESC_DATETIME_INTERVAL_CODE字段设置为0。

如果SQL_DESC_TYPE设置为冗长的日期时间或区间数据类型（SQL_DATETIME或SQL_INTERVAL），SQL_DESC_DATETIME_INTERVAL_CODE字段设置为相应子代码，则SQL_DESC_CONCISE TYPE 字段被设置为相应的简洁类型。 尝试将SQL_DESC_TYPE设置为简洁的日期时间或区间类型之一，将返回 SQLSTATE HY021（不一致描述符信息）。

当SQL_DESC_TYPE字段通过调用 SQLBindCol、 SQLBindParameter或 SQLSetDescField设置时，以下字段将设置为以下默认值，如下表所示。 同一记录中剩余字段的值未定义。

当应用程序调用 SQLSetDescField 来设置描述符字段而非调用 SQLSetDescRec 时，应用程序必须先声明数据类型。 当它发生时，前表中其他字段会被隐式设置。 如果隐式设置的值中任何不可接受，应用程序可以调用 SQLSetDescField 或 SQLSetDescRec 显式设置不可接受值。

SQL_DESC_TYPE_NAME [实现描述符]
这个只读的 SQLCHAR * 记录字段包含数据源相关的类型名称（例如 “CHAR”、“VARCHAR” 等）。 如果数据类型名称未知，该变量包含一个空字符串。

SQL_DESC_UNNAMED [实现描述符]
驱动程序在设置SQL_DESC_NAME字段时，将行描述符中的SQLSMALLINT记录字段设置为SQL_NAMED或SQL_UNNAMED。 如果SQL_DESC_NAME字段包含列别名，或者列别名不适用，驱动程序将SQL_DESC_UNNAMED字段设置为SQL_NAMED。 如果应用程序将IPD的SQL_DESC_NAME字段设置为参数名或别名，驱动程序将IPD的SQL_DESC_UNNAMED字段设置为SQL_NAMED。 如果没有列名或列别名，驱动将SQL_DESC_UNNAMED字段设置为SQL_UNNAMED。

应用程序可以将IPD的SQL_DESC_UNNAMED字段设置为SQL_UNNAMED。 如果应用程序尝试将IPD的SQL_DESC_UNNAMED字段设置为SQL_NAMED，驱动程序会返回SQLSTATE HY091（描述符字段无效标识符）。 IRD的SQL_DESC_UNNAMED字段是只读的;如果应用程序尝试设置 SQLSTATE HY091（描述符字段标识符无效）将返回该标识符。

SQL_DESC_UNSIGNED [实现描述符]
当列类型无符号或非数字时，该只读 SQLSMALLINT 记录字段设置为 SQL_TRUE;如果列类型有符号，则设置为 SQL_FALSE。

SQL_DESC_UPDATABLE [IRDS]
这个只读的 SQLSMALLINT 记录字段设置为以下值之一：

• SQL_ATTR_READ_ONLY 如果结果集列是只读的。

• SQL_ATTR_WRITE 如果结果集列是读写。

• SQL_ATTR_READWRITE_UNKNOWN如果不知道结果集列是否可更新。

SQL_DESC_UPDATABLE描述的是结果集中该列的可更新性，而非基表中的该列。 该结果集列所依据的基表中该列的可更新性可能与该字段中的值不同。 列是否可更新取决于数据类型、用户权限以及结果集本身的定义。 如果不确定某列是否可更新，应返回SQL_ATTR_READWRITE_UNKNOWN。

一致性检查

每当应用程序传递ARD、APD或IPD SQL_DESC_DATA_PTR字段的值时，驱动程序会自动执行一致性检查。 如果任何字段与其他字段不一致， SQLSetDescField 将返回 SQLSTATE HY021（描述符信息不一致）。 更多信息请参见 SQLSetDescRec 中的“一致性检查”。

相关函数

另请参阅

ODBC 头文件
ODBC API 参考