SQLSetDescField 函数

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

摘要
SQLSetDescField 设置描述符记录的单个字段的值。

语法

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

参数

DescriptorHandle
[输入]描述符句柄。

RecNumber
[输入]指示包含应用程序要设置的字段的描述符记录。 描述符记录编号为 0,记录号 0 是书签记录。 对于标头字段, 将忽略 RecNumber 参数。

FieldIdentifier
[输入]指示要设置其值的描述符的字段。 有关详细信息,请参阅“注释”部分中的“FieldIdentifier 参数”。

ValuePtr
[输入]指向包含描述符信息或整数值的缓冲区的指针。 数据类型取决于 FieldIdentifier 的值。 如果 ValuePtr 是整数值,则根据 FieldIdentifier 参数的值,可以将该值视为 8 个字节 (SQLLEN) 、4 个字节 (SQLINTEGER) 或 2 个字节 (SQLSMALLINT) 。

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

如果 FieldIdentifier 是 ODBC 定义的字段, ValuePtr 是整数,则 忽略 BufferLength

如果 FieldIdentifier 是驱动程序定义的字段,则应用程序通过设置 BufferLength 参数来指示字段的性质。 BufferLength 可以具有以下值:

  • 如果 ValuePtr 是指向字符串的指针, 则 BufferLength 是字符串的长度或SQL_NTS。

  • 如果 ValuePtr 是指向二进制缓冲区的指针,则应用程序会将SQL_LEN_BINARY_ATTR (长度) 宏的结果放在 BufferLength 中。 这会在 BufferLength 中放置负值。

  • 如果 ValuePtr 是指向字符串或二进制字符串以外的值的指针,则 BufferLength 应具有值SQL_IS_POINTER。

  • 如果 ValuePtr 包含固定长度的值,则 BufferLength 是适当SQL_IS_INTEGER、SQL_IS_UINTEGER、SQL_IS_SMALLINT或SQL_IS_USMALLINT。

返回

SQL_SUCCESS、SQL_SUCCESS_WITH_INFO、SQL_ERROR或SQL_INVALID_HANDLE。

诊断

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

SQLSTATE 错误 说明
01000 常规警告 特定于驱动程序的信息性消息。 (函数返回 SQL_SUCCESS_WITH_INFO.)
01S02 选项值已更改 驱动程序不支持 在 *ValuePtr (中指定的值(如果 ValuePtr 是指针) 或 ValuePtr 中的值 (如果 ValuePtr 是整数值) ,或 *ValuePtr 由于实现工作条件无效,因此驱动程序替换了类似的值。 (函数返回 SQL_SUCCESS_WITH_INFO.)
07009 描述符索引无效 FieldIdentifier 参数是一个记录字段,RecNumber 参数为 0,描述符Handle 参数引用 IPD 句柄。

RecNumber 参数小于 0,描述符Handle 参数引用了 ARD 或 APD。

RecNumber 参数大于数据源可以支持的最大列数或参数数,以及引用 APD 或 ARD 的描述符Handle 参数。

(DM) FieldIdentifier 参数SQL_DESC_COUNT, *ValuePtr 参数小于 0。

RecNumber 参数等于 0,描述符Handle 参数引用了隐式分配的 APD。 (显式分配的应用程序描述符不会发生此错误,因为目前不知道显式分配的应用程序描述符是 APD 还是 ARD,直到执行时间。)
08S01 通信链接失败 驱动程序与驱动程序连接到的数据源之间的通信链接在函数完成处理之前失败。
22001 字符串数据,右截断 FieldIdentifier 参数SQL_DESC_NAME,BufferLength 参数的值大于 SQL_MAX_IDENTIFIER_LEN。
HY000 常规错误 发生错误,其中没有特定的 SQLSTATE,未定义特定于实现的 SQLSTATE。 *MessageText 缓冲区中 SQLGetDiagRec 返回的错误消息描述错误及其原因。
HY001 内存分配错误 驱动程序无法分配支持执行或完成函数所需的内存。
HY010 函数序列错误 (DM) 描述符Handle一个 StatementHandle 相关联,其中异步执行函数 (不是调用此函数) ,并且仍在调用此函数时执行。

(DM) SQLExecute、SQLExecDirectSQLBulkOperationsSQLSetPos 针对与描述符Handle 关联并返回SQL_NEED_DATA的 StatementHandle 在为所有数据执行参数或列发送数据之前调用此函数。

(DM) 为与 描述符Handle 关联的连接句柄调用异步执行函数。 调用 SQLSetDescField 函数时,此异步函数仍在执行。

(DM) SQLExecute、SQLExecDirectSQLMoreResults 为与描述符Handle 关联的语句句柄之一调用并返回SQL_PARAM_DATA_AVAILABLE。 在检索所有流式处理参数的数据之前调用此函数。
HY013 内存管理错误 由于无法访问基础内存对象,因此无法处理函数调用,可能是由于内存条件低。
HY016 无法修改实现行描述符 描述符Handle 参数与 IRD 相关联,FieldIdentifier 参数未SQL_DESC_ARRAY_STATUS_PTR或SQL_DESC_ROWS_PROCESSED_PTR。
HY021 描述符信息不一致 SQL_DESC_TYPE和SQL_DESC_DATETIME_INTERVAL_CODE字段不构成有效的 ODBC SQL 类型或 IP) D 的有效特定于驱动程序的SQL类型 (,也不构成 API 或 ARD) 的有效 ODBC C 类型 (。

在一致性检查期间检查的描述符信息不一致。 (SQLSetDescRec.) 中查看“一致性检查”
HY090 字符串或缓冲区长度无效 (DM) *ValuePtr 是一个字符串, BufferLength 小于零,但不等于SQL_NTS。

(DM) 驱动程序是 ODBC 2*.x* 驱动程序,描述符为 ARD, ColumnNumber 参数设置为 0,为参数 BufferLength 指定的值不等于 4。
HY091 描述符字段标识符无效 FieldIdentifier 参数指定的值不是 ODBC 定义的字段,不是实现定义的值。

FieldIdentifier 参数对描述符Handle 参数无效。

FieldIdentifier 参数是一个只读的 ODBC 定义字段。
HY092 属性/选项标识符无效 *ValuePtr 中的值对 FieldIdentifier 参数无效。

FieldIdentifier 参数SQL_DESC_UNNAMED,ValuePtr SQL_NAMED。
HY105 参数类型无效 (DM) 为SQL_DESC_PARAMETER_TYPE字段指定的值无效。 (有关详细信息,请参阅 SQLBindParameter.) 中的“InputOutputType 参数”部分
HY117 由于未知事务状态,连接暂停。 仅允许断开连接和只读函数。 (DM) 有关挂起状态的详细信息,请参阅 ODBC 3.8 中的新增功能。
HYT01 超过连接超时时间 在数据源响应请求之前,连接超时期限已过期。 连接超时期限通过 SQLSetConnectAttr 设置,SQL_ATTR_CONNECTION_TIMEOUT。
IM001 驱动程序不支持此函数 (DM) 与 描述符Handle 关联的驱动程序不支持该函数。

注释

应用程序可以调用 SQLSetDescField 来一次设置任何描述符字段。 对 SQLSetDescField 的一次调用在单个描述符中设置单个字段。 可以调用此函数以在任何描述符类型中设置任何字段,前提是可以设置该字段。 (请参阅本部分后面的表。)

注意

如果对 SQLSetDescField 的调用失败,则未定义 RecNumber 参数标识的描述符记录的内容。

可以调用其他函数以使用函数的单个调用设置多个描述符字段。 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字段) 的各种字段。 SQLBindColSQLBindParameter 可用于为列或参数的绑定制定完整的规范。 这些函数使用一个函数调用设置一组特定的描述符字段。

可以通过向绑定指针添加偏移量来调用 SQLSetDescField 来更改绑定缓冲区, (SQL_DESC_DATA_PTR、SQL_DESC_INDICATOR_PTR或SQL_DESC_OCTET_LENGTH_PTR) 。 这会更改绑定缓冲区,而无需调用 SQLBindColSQLBindParameter,这样应用程序就可以更改SQL_DESC_DATA_PTR而不更改其他字段,例如SQL_DESC_DATA_TYPE。

如果应用程序调用 SQLSetDescField 来设置除SQL_DESC_COUNT以外的任何字段或延迟字段SQL_DESC_DATA_PTR、SQL_DESC_OCTET_LENGTH_PTR或SQL_DESC_INDICATOR_PTR,则记录将变为未绑定。

使用相应的 FieldIdentifier 调用 SQLSetDescField 来设置描述符标头字段。 许多标头字段也是语句属性,因此也可以通过调用 SQLSetStmtAttr 来设置它们。 这样,应用程序就可以设置描述符字段,而无需首先获取描述符句柄。 调用 SQLSetDescField 设置标头字段时, 将忽略 RecNumber 参数。

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

注意

在调用 SQLSetDescField 以设置书签字段之前,应始终设置语句属性SQL_ATTR_USE_BOOKMARKS。 虽然这不是强制性的,但强烈建议这样做。

设置描述符字段序列

通过调用 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设置为 null 指针,取消绑定记录。 这会强制应用程序在描述符记录可用之前按顺序完成正确的步骤。

描述符字段的初始化

分配描述符时,可以将描述符中的字段初始化为默认值、不带默认值初始化或未为描述符类型定义字段。 下表指示每种类型的描述符的初始化,其中“D”表示字段是使用默认值初始化的,“ND”指示字段在不使用默认值的情况下初始化字段。 如果显示数字,则字段的默认值为该数字。 这些表还指示字段是读/写 (R/W) 还是只读 (R) 。

仅当已准备或执行语句并且已填充 IRD 之后,IRD 的字段才具有默认值,而不是在已分配语句句柄或描述符时填充。 在填充 IRD 之前,任何获取 IRD 字段访问权限的尝试都将返回错误。

某些描述符字段针对一个或多个描述符类型(但并非全部)定义,这些描述符类型 (ARD 和 IRD,以及) APD 和 IPD。 如果未为一种类型的描述符定义字段,则使用该描述符的任何函数都不需要该字段。

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

标头字段的初始化在下表中概述。

标头字段名称 类型 R/W 默认
SQL_DESC_ALLOC_TYPE SQLSMALLINT ARD: R APD: R IRD: R IPD: R ARD:为隐式或显式SQL_DESC_ALLOC_USER SQL_DESC_ALLOC_AUTO

APD:为隐式或显式SQL_DESC_ALLOC_USER SQL_DESC_ALLOC_AUTO

IRD:SQL_DESC_ALLOC_AUTO

IPD:SQL_DESC_ALLOC_AUTO
SQL_DESC_ARRAY_SIZE SQLULEN ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD:[1] APD:[1] IRD: 未使用的 IPD: 未使用
SQL_DESC_ARRAY_STATUS_PTR SQLUSMALLINT* ARD: R/W APD: R/W IRD: R/W IPD: R/W ARD: Null ptr APD: Null ptr IRD: Null ptr IPD: Null ptr
SQL_DESC_BIND_OFFSET_PTR SQLLEN* ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD:Null ptr APD:Null ptr IRD:未使用的 IPD:未使用
SQL_DESC_BIND_TYPE SQLINTEGER ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD: SQL_BIND_BY_COLUMN

APD:SQL_BIND_BY_COLUMN

IRD:未使用

IPD:未使用
SQL_DESC_COUNT SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: 0 APD: 0 IRD: D IPD: 0
SQL_DESC_ROWS_PROCESSED_PTR SQLULEN* ARD:未使用的 APD:未使用的 IRD:R/W IPD:R/W ARD:未使用的 APD:未使用的 IRD:Null ptr IPD:Null ptr

[1] 仅当驱动程序自动填充 IPD 时,才会定义这些字段。 否则,它们未定义。 如果应用程序尝试设置这些字段,将返回 SQLSTATE HY091 (描述符字段标识符) 无效。

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

记录字段名称 类型 R/W 默认
SQL_DESC_AUTO_UNIQUE_VALUE SQLINTEGER ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_BASE_COLUMN_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_BASE_TABLE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_CASE_SENSITIVE SQLINTEGER ARD:未使用的 APD:未使用的 IRD:R IPD: R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_CATALOG_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_CONCISE_TYPE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD:SQL_C_默认 APD:SQL_C_默认 IRD:D IPD: ND
SQL_DESC_DATA_PTR SQLPOINTER ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD: Null ptr APD: Null ptr IRD: 未使用的 IPD: 未使用[2]
SQL_DESC_DATETIME_INTERVAL_CODE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DATETIME_INTERVAL_PRECISION SQLINTEGER ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_DISPLAY_SIZE SQLLEN ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_FIXED_PREC_SCALE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD: R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_INDICATOR_PTR SQLLEN * ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD:Null ptr APD:Null ptr IRD:未使用的 IPD:未使用
SQL_DESC_LABEL SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_LENGTH SQLULEN ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_LITERAL_PREFIX SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_LITERAL_SUFFIX SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_LOCAL_TYPE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD: R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NULLABLE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD: R ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_NUM_PREC_RADIX SQLINTEGER ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH SQLLEN ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_OCTET_LENGTH_PTR SQLLEN * ARD:R/W APD:R/W IRD:未使用的 IPD:未使用 ARD:Null ptr APD:Null ptr IRD:未使用的 IPD:未使用
SQL_DESC_PARAMETER_TYPE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:未使用的 IPD:R/W ARD:未使用的 APD:未使用的 IRD:未使用的 IPD:D=SQL_PARAM_INPUT
SQL_DESC_PRECISION SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_ROWVER SQLSMALLINT ARD:未使用

APD:未使用

IRD:R

IPD:R
ARD:未使用

APD:未使用

IRD:ND

IPD:ND
SQL_DESC_SCALE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_SCHEMA_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_SEARCHABLE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_TABLE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用
SQL_DESC_TYPE SQLSMALLINT ARD: R/W APD: R/W IRD: R IPD: R/W ARD: SQL_C_DEFAULT APD: SQL_C_DEFAULT IRD: D IPD: ND
SQL_DESC_TYPE_NAME SQLCHAR * ARD:未使用的 APD:未使用的 IRD:R IPD: R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_UNNAMED SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:R/W ARD: ND APD: ND IRD: D IPD: ND
SQL_DESC_UNSIGNED SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD: R ARD:未使用的 APD:未使用的 IRD:D IPD:D[1]
SQL_DESC_UPDATABLE SQLSMALLINT ARD:未使用的 APD:未使用的 IRD:R IPD:未使用 ARD:未使用的 APD:未使用的 IRD:D IPD:未使用

[1] 仅当驱动程序自动填充 IPD 时,才会定义这些字段。 否则,它们未定义。 如果应用程序尝试设置这些字段,将返回 SQLSTATE HY091 (描述符字段标识符) 无效。

[2] IPD 中的SQL_DESC_DATA_PTR字段可以设置为强制进行一致性检查。 在对 SQLGetDescField 或 SQLGetDescRec后续调用中,不需要驱动程序才能返回已设置为SQL_DESC_DATA_PTR的值。

FieldIdentifier 参数

FieldIdentifier 参数指示要设置的描述符字段。 描述符包含 描述符标头, 由下一部分所述的标题字段“标头字段”和零个或多个 描述符记录组成, 由“标头字段”部分后面的节中所述的记录字段组成。

标头字段

每个描述符都有一个标头,其中包含以下字段:

SQL_DESC_ALLOC_TYPE [全部]
此只读 SQLSMALLINT 标头字段指定是由驱动程序自动分配描述符还是由应用程序显式分配。 应用程序可以获取但不修改此字段。 如果驱动程序自动分配描述符,则字段设置为SQL_DESC_ALLOC_AUTO。 如果应用程序显式分配了描述符,则驱动程序将其设置为SQL_DESC_ALLOC_USER。

SQL_DESC_ARRAY_SIZE [应用程序描述符]
在 ARD 中,此 SQLULEN 标头字段指定行集中的行数。 这是通过调用 SQLFetch 或 SQLFetchScroll调用 SQLBulkOperationsSQLSetPos 来返回的行数。

在 APD 中,此 SQLULEN 标头字段指定每个参数的值数。

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

还可以使用 SQL_ATTR_ROW_ARRAY_SIZE 属性调用 SQLSetStmtAttr 来设置 ARD 中的此字段。 还可以使用 SQL_ATTR_PARAMSET_SIZE 属性调用 SQLSetStmtAttr 来设置 APD 中的此字段。

SQL_DESC_ARRAY_STATUS_PTR [全部]
对于每个描述符类型,此 SQLUSMALLINT * 标头字段指向 SQLUSMALLINT 值的数组。 这些数组命名如下:行状态数组 (IRD) 、参数状态数组 (IPD) 、行操作数组 (ARD) ,以及参数操作数组 (APD) 。

在 IRD 中,此标头字段指向在调用 SQLBulkOperationsSQLFetch、SQLFetch、SQLFetchScrollSQLSetPos 后包含状态值的行状态数组。 数组包含的元素数与行集中的行数一样多。 应用程序必须分配 SQLUSMALLINTs 的数组,并将此字段设置为指向数组。 默认情况下,该字段设置为 null 指针。 驱动程序将填充数组 - 除非SQL_DESC_ARRAY_STATUS_PTR字段设置为 null 指针,在这种情况下,不会生成状态值,并且不会填充数组。

注意

如果应用程序设置 IRD SQL_DESC_ARRAY_STATUS_PTR字段指向的行状态数组的元素,则驱动程序行为是未定义的。

该数组最初由对 SQLBulkOperationsSQLFetch、SQLFetchScrollSQLSetPos 的调用填充。 如果调用未返回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 来设置。

仅当返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO后,IRD 的SQL_DESC_ARRAY_STATUS_PTR字段才有效。 如果返回代码不是其中之一,则SQL_DESC_ROWS_PROCESSED_PTR指向的位置未定义。

在 IPD 中,此标头字段指向一个参数状态数组,其中包含对 SQLExecuteSQLExecDirect 的调用后每个参数值集的状态信息。 如果对 SQLExecuteSQLExecDirect 的调用未返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,则此字段指向的数组的内容未定义。 应用程序必须分配 SQLUSMALLINT 数组,并将此字段设置为指向该数组。 驱动程序将填充数组 - 除非将SQL_DESC_ARRAY_STATUS_PTR字段设置为 null 指针,在这种情况下,不会生成状态值,并且不会填充数组。 数组中的元素可以包含以下值:

  • 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,则驱动程序可能无法在 row 中执行该操作。)

  • SQL_ROW_IGNORE:使用 SQLSetPos 从大容量操作中排除行。

如果未设置数组的元素,则大容量操作中包括所有行。 如果 ARD SQL_DESC_ARRAY_STATUS_PTR 字段中的值为 null 指针,则大容量操作中包括所有行;解释与指向有效数组的指针和数组的所有元素SQL_ROW_PROCEED相同。 如果数组中的元素设置为SQL_ROW_IGNORE,则忽略行的行状态数组中的值不会更改。

还可以使用 SQL_ATTR_ROW_OPERATION_PTR 属性调用 SQLSetStmtAttr 来设置 ARD 中的此字段。

在 APD 中,此标头字段指向可由应用程序设置的值的参数操作数组,以指示在调用 SQLExecuteSQLExecDirect 时是否忽略此组参数。 数组中的元素可以包含以下值:

  • SQL_PARAM_PROCEED:参数集包含在 SQLExecuteSQLExecDirect 调用中。

  • SQL_PARAM_IGNORE:从 SQLExecuteSQLExecDirect 调用中排除参数集。

如果未设置数组的元素,则数组中的所有参数集都用于 SQLExecuteSQLExecDirect 调用。 如果 APD SQL_DESC_ARRAY_STATUS_PTR 字段中的值是空指针,则使用所有参数集;解释与指向有效数组的指针和数组的所有元素SQL_PARAM_PROCEED相同。

还可以使用 SQL_ATTR_PARAM_OPERATION_PTR 属性调用 SQLSetStmtAttr 来设置 APD 中的此字段。

SQL_DESC_BIND_OFFSET_PTR [应用程序描述符]
此 SQLLEN * 标头字段指向绑定偏移量。 默认情况下,它设置为 null 指针。 如果此字段不是 null 指针,驱动程序将取消引用指针,并将取消引用值添加到在描述符记录中具有非 null 值的每个延迟字段, (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字段中的值。 如果偏移量更改为其他值,新值仍将直接添加到每个描述符字段中的值。 新偏移量不会添加到字段值加上任何以前的偏移量。

此字段是 延迟字段:它不是在设置时使用,而是在驱动程序稍后需要确定数据缓冲区的地址时使用。

还可以使用 SQL_ATTR_ROW_BIND_OFFSET_PTR 属性调用 SQLSetStmtAttr 来设置 ARD 中的此字段。 还可以使用 SQL_ATTR_PARAM_BIND_OFFSET_PTR 属性调用 SQLSetStmtAttr 来设置 ARD 中的此字段。

有关详细信息,请参阅 SQLFetchScrollSQLBindParameter 中行绑定的说明。

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

在 ARD 中,当在关联的语句句柄上调用 SQLFetchScrollSQLFetch 时,此字段指定绑定方向。

若要为列选择列的按列绑定,此字段设置为SQL_BIND_BY_COLUMN (默认) 。

还可以使用 SQL_ATTR_ROW_BIND_TYPE 属性调用 SQLSetStmtAttr 来设置 ARD 中的此字段。

在 APD 中,此字段指定要用于动态参数的绑定方向。

若要为参数选择列式绑定,此字段设置为SQL_BIND_BY_COLUMN (默认) 。

还可以通过使用 SQL_ATTR_PARAM_BIND_TYPE 属性调用 SQLSetStmtAttr 来设置 APD 中的此字段。

SQL_DESC_COUNT [全部]
此 SQLSMALLINT 标头字段指定包含数据的最高编号记录的基于 1 的索引。 当驱动程序为描述符设置数据结构时,还必须设置SQL_DESC_COUNT字段以显示有多少记录是重要的。 当应用程序分配此数据结构的实例时,它不必指定要为其预留空间的记录数。 当应用程序指定记录的内容时,驱动程序会采取任何必需的操作,以确保描述符句柄引用足够大小的数据结构。

如果字段位于 ARD) 或绑定的所有参数(如果字段位于 APD) 中,则SQL_DESC_COUNT不是 (绑定 (的所有数据列的计数,而是最大编号记录的数目。 如果编号最高的列或参数未绑定,则SQL_DESC_COUNT更改为下一个编号最高的列或参数的数目。 如果列或具有小于最大编号列数的列数的参数未绑定 (,则调用 TargetValuePtr 参数设置为 null 指针的 SQLBindCol,或者将 ParameterValuePtr 参数设置为 null 指针的 SQLBindParameter) ,SQL_DESC_COUNT不会更改。 如果附加列或参数与数字大于包含数据的最高编号记录的数字绑定,驱动程序会自动增加SQL_DESC_COUNT字段中的值。 如果使用 SQL_UNBIND 选项调用 SQLFreeStmt 来取消绑定所有列,则 ARD 和 IRD 中的SQL_DESC_COUNT字段设置为 0。 如果使用 SQL_RESET_PARAMS 选项调用 SQLFreeStmt ,则 APD 和 IPD 中的SQL_DESC_COUNT字段设置为 0。

SQL_DESC_COUNT中的值可以通过调用 SQLSetDescField 由应用程序显式设置。 如果显式减少SQL_DESC_COUNT中的值,则有效删除SQL_DESC_COUNT中大于新值的所有记录。 如果SQL_DESC_COUNT中的值显式设置为 0,并且字段位于 ARD 中,则释放绑定书签列以外的所有数据缓冲区。

ARD 的此字段中的记录计数不包括绑定书签列。 取消绑定书签列的唯一方法是将SQL_DESC_DATA_PTR字段设置为 null 指针。

SQL_DESC_ROWS_PROCESSED_PTR [实现描述符]
在 IRD 中,此 SQLULEN * 标头字段指向一个缓冲区,该缓冲区包含调用 SQLFetch 或 SQLFetchScroll 后提取的行数,或调用 SQLBulkOperationsSQLSetPos(包括错误行)在大容量操作中受影响的行数。

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

SQL_DESC_ROWS_PROCESSED_PTR仅在对 IRD 字段 SQL_SUCCESS) SQL_SUCCESS_WITH_INFO或 SQLExecute、SQLExecuteSQLExecDirectSQLParamData () 调用 SQLFetch 或 SQLFetchScroll ( (后才有效。 如果此字段指向的缓冲区中填充的调用不返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,则缓冲区的内容是未定义的,除非它返回SQL_NO_DATA,在这种情况下,缓冲区中的值设置为 0。

还可以使用 SQL_ATTR_ROWS_FETCHED_PTR 属性调用 SQLSetStmtAttr 来设置 ARD 中的此字段。 还可以使用 SQL_ATTR_PARAMS_PROCESSED_PTR 属性调用 SQLSetStmtAttr 来设置 APD 中的此字段。

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

记录字段

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

SQL_DESC_AUTO_UNIQUE_VALUE [IRD]
如果列是自动递增列,则此只读 SQLINTEGER 记录字段包含SQL_TRUE;如果列不是自动递增列,则SQL_FALSE。 此字段是只读的,但基础自动递增列不一定是只读的。

SQL_DESC_BASE_COLUMN_NAME [IRD]
此只读 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字段中的值是相互依赖的。 每次设置其中一个字段时,还必须设置另一个字段。 可以通过调用 SQLBindCol 或SQLBindParameterSQLSetDescField 来设置SQL_DESC_CONCISE_TYPE。 可以通过调用 SQLSetDescFieldSQLSetDescRec 来设置SQL_DESC_TYPE。

如果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 参数为 null 指针,或者 ARD 中的SQL_DESC_DATA_PTR字段是通过调用 SQLSetDescFieldSQLSetDescRec 设置为 null 指针,则 ARD 的SQL_DESC_DATA_PTR字段指定的列是未绑定的。 如果SQL_DESC_DATA_PTR字段设置为 null 指针,则不会影响其他字段。

如果在此字段指向的缓冲区中填充的 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 [全部]
当SQL_DESC_TYPE字段SQL_DATETIME或SQL_INTERVAL时,此 SQLSMALLINT 记录字段包含特定日期/时间或间隔数据类型的子代码。 这适用于 SQL 和 C 数据类型。 该代码由数据类型名称组成,数据类型名称替换为“TYPE”或“C_TYPE” (日期/时间类型) ,或“CODE”替换为“INTERVAL”或“C_INTERVAL” (间隔类型) 。

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

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

日期/时间类型 DATETIME_INTERVAL_CODE
SQL_TYPE_DATE/SQL_C_TYPE_DATE SQL_CODE_DATE
SQL_TYPE_TIME/SQL_C_TYPE_TIME SQL_CODE_TIME
SQL_TYPE_TIMESTAMP/SQL_C_TYPE_TIMESTAMP SQL_CODE_TIMESTAMP

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

间隔类型 DATETIME_INTERVAL_CODE
SQL_INTERVAL_DAY/SQL_C_INTERVAL_DAY SQL_CODE_DAY
SQL_INTERVAL_DAY_TO_HOUR/SQL_C_INTERVAL_DAY_TO_HOUR SQL_CODE_DAY_TO_HOUR
SQL_INTERVAL_DAY_TO_MINUTE/SQL_C_INTERVAL_DAY_TO_MINUTE SQL_CODE_DAY_TO_MINUTE
SQL_INTERVAL_DAY_TO_SECOND/SQL_C_INTERVAL_DAY_TO_SECOND SQL_CODE_DAY_TO_SECOND
SQL_INTERVAL_HOUR/SQL_C_INTERVAL_HOUR SQL_CODE_HOUR
SQL_INTERVAL_HOUR_TO_MINUTE/SQL_C_INTERVAL_HOUR_TO_MINUTE SQL_CODE_HOUR_TO_MINUTE
SQL_INTERVAL_HOUR_TO_SECOND/SQL_C_INTERVAL_HOUR_TO_SECOND SQL_CODE_HOUR_TO_SECOND
SQL_INTERVAL_MINUTE/SQL_C_INTERVAL_MINUTE SQL_CODE_MINUTE
SQL_INTERVAL_MINUTE_TO_SECOND/SQL_C_INTERVAL_MINUTE_TO_SECOND SQL_CODE_MINUTE_TO_SECOND
SQL_INTERVAL_MONTH/SQL_C_INTERVAL_MONTH SQL_CODE_MONTH
SQL_INTERVAL_SECOND/SQL_C_INTERVAL_SECOND SQL_CODE_SECOND
SQL_INTERVAL_YEAR/SQL_C_INTERVAL_YEAR SQL_CODE_YEAR
SQL_INTERVAL_YEAR_TO_MONTH/SQL_C_INTERVAL_YEAR_TO_MONTH SQL_CODE_YEAR_TO_MONTH

有关数据间隔和此字段的详细信息,请参阅 数据类型标识符和描述符

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为 null 指针,则当驱动程序尝试在调用 SQLFetch 或 SQLFetchScroll 后填充缓冲区时,将返回所需的 SQLSTATE 22002 (指示器变量,但未提供) 。 如果对 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 指针,则应用程序不能使用此描述符记录来指定 NULL 参数。

此字段是 延迟字段:在设置时不使用它,但稍后由驱动程序指示 ARD) 的可为空性 (,或确定 APD) 的可为空性 (。

SQL_DESC_LABEL [IRD]
此只读 SQLCHAR * 记录字段包含列标签或标题。 如果该列没有标签,则此变量包含列名。 如果列未命名且未标记,则此变量包含空字符串。

SQL_DESC_LENGTH [全部]
此 SQLULEN 记录字段是字符串的最大长度或实际长度(以字节为单位)。 它是固定长度数据类型的最大长度,或可变长度数据类型的实际长度。 其值始终排除结束字符串的 null 终止字符。 对于类型为SQL_TYPE_DATE、SQL_TYPE_TIME、SQL_TYPE_TIMESTAMP或SQL间隔数据类型之一的值,此字段的字符串表示形式的长度为日期/时间或间隔值。

此字段中的值可能与 ODBC 2*.x* 中定义的“length”值不同。 有关详细信息,请参阅 附录 D:数据类型

SQL_DESC_LITERAL_PREFIX [IRD]
此只读 SQLCHAR * 记录字段包含驱动程序识别为此数据类型文本的前缀的字符或字符。 此变量包含文本前缀不适用的数据类型的空字符串。

SQL_DESC_LITERAL_SUFFIX [IRD]
此只读 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 值,则此只读 SQLSMALLINT 记录字段SQL_NULLABLE,如果列没有 NULL 值,则SQL_NO_NULLS列是否具有 NULL 值,或者如果不知道该列是否接受 NULL 值,则SQL_NULLABLE_UNKNOWN。 此字段与结果集列(而不是基列)相关。

在 IPD 中,此字段始终设置为SQL_NULLABLE,因为动态参数始终可为 null 且无法由应用程序设置。

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 记录字段包含字符串或二进制数据类型的长度(以字节为单位)。 对于固定长度字符或二进制类型,这是实际长度(以字节为单位)。 对于可变长度字符或二进制类型,这是最大长度(以字节为单位)。 此值始终排除实现描述符的 null 终止字符的空间,并且始终包含应用程序描述符的 null 终止字符的空间。 对于应用程序数据,此字段包含缓冲区的大小。 对于 APD,此字段仅用于输出或输入/输出参数。

SQL_DESC_OCTET_LENGTH_PTR [应用程序描述符]
此 SQLLEN * 记录字段指向一个变量,该变量包含参数描述符) 或行描述符) 绑定列值 (动态参数 (的总长度(以字节为单位)。

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

如果 ARD 的OCTET_LENGTH_PTR字段为空指针,则驱动程序不会返回列的长度信息。 如果 APD 的SQL_DESC_OCTET_LENGTH_PTR字段为 null 指针,驱动程序假定字符串和二进制值以 null 结尾。 (二进制值不应为 null 终止,但应提供一个长度以避免截断。)

如果在此字段指向的缓冲区中填充的 SQLFetch 或 SQLFetchScroll 调用未返回SQL_SUCCESS或SQL_SUCCESS_WITH_INFO,则未定义缓冲区的内容。 此字段是 延迟字段。 它在设置时不使用,但稍后由驱动程序用来确定或指示数据的八进制长度。

SQL_DESC_PARAMETER_TYPE [IPD]
此 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_ATTR_ENABLE_AUTO_IPD语句属性SQL_FALSE) ,则字段默认设置为SQL_PARAM_INPUT。 应用程序应在 IPD 中为不是输入参数的参数设置此字段。

SQL_DESC_PRECISION [全部]
此 SQLSMALLINT 记录字段包含精确数值类型的位数、mantissa (二进制精度) 中的位数,或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 为 SQL_ROWVER 调用 SQLSpecialColumns ,以确定列是否自动更新。

SQL_DESC_SCALE [全部]
此 SQLSMALLINT 记录字段包含十进制和数值数据类型的已定义刻度。 该字段为所有其他数据类型未定义。

此字段中的值可能与 ODBC 2*.x* 中定义的“scale”的值不同。 有关详细信息,请参阅 附录 D:数据类型

SQL_DESC_SCHEMA_NAME [IRD]
此只读 SQLCHAR * 记录字段包含包含列的基表的架构名称。 如果列是表达式,或者列是视图的一部分,则返回值依赖于驱动程序。 如果数据源不支持架构或架构名称无法确定,则此变量包含空字符串。

SQL_DESC_SEARCHABLE [IRD]
此只读 SQLSMALLINT 记录字段设置为以下值之一:

  • 如果列不能在 WHERE 子句中使用,则SQL_PRED_NONE。 (这与 ODBC 2*.x*.) 中的SQL_UNSEARCHABLE值相同

  • 如果列可以在 WHERE 子句中使用,但只能与 LIKE 谓词一起使用,则SQL_PRED_CHAR。 (这与 ODBC 2*.x*.) 中的SQL_LIKE_ONLY值相同

  • SQL_PRED_BASIC如果 列可用于 WHERE 子句以及除 LIKE 之外的所有比较运算符。 (这与 ODBC 2*.x*.) 中的SQL_EXCEPT_LIKE值相同

  • 如果列可用于具有任何比较运算符的 WHERE 子句,则SQL_PRED_SEARCHABLE。

SQL_DESC_TABLE_NAME [IRD]
此只读 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字段中的值相互依赖。 每次设置其中一个字段时,还必须设置另一个字段。 可以通过调用 SQLSetDescFieldSQLSetDescRec 来设置SQL_DESC_TYPE。 可以通过调用 SQLBindCol 或SQLBindParameterSQLSetDescField 来设置SQL_DESC_CONCISE_TYPE。

如果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 (不一致的描述符信息) 。

当通过调用 SQLBindColSQLBindParameterSQLSetDescField 设置SQL_DESC_TYPE字段时,以下字段将设置为以下默认值,如下表所示。 未定义同一记录的剩余字段的值。

SQL_DESC_TYPE的值 其他字段隐式设置
SQL_CHAR、SQL_VARCHAR、SQL_C_CHAR、SQL_C_VARCHAR SQL_DESC_LENGTH设置为 1。 SQL_DESC_PRECISION设置为 0。
SQL_DATETIME 当SQL_DESC_DATETIME_INTERVAL_CODE设置为SQL_CODE_DATE或SQL_CODE_TIME时,SQL_DESC_PRECISION设置为 0。 当它设置为SQL_DESC_TIMESTAMP时,SQL_DESC_PRECISION设置为 6。
SQL_DECIMAL、SQL_NUMERIC、SQL_C_NUMERIC SQL_DESC_SCALE设置为 0。 SQL_DESC_PRECISION设置为相应数据类型的实现定义的精度。

请参阅 SQL to C:数字 ,了解如何手动绑定SQL_C_NUMERIC值。
SQL_FLOAT、SQL_C_FLOAT SQL_DESC_PRECISION设置为SQL_FLOAT实现定义的默认精度。
SQL_INTERVAL SQL_DESC_DATETIME_INTERVAL_CODE设置为间隔数据类型时,SQL_DESC_DATETIME_INTERVAL_PRECISION设置为 2, (默认间隔前导精度) 。 当间隔具有秒分量时,SQL_DESC_PRECISION设置为 6 (默认间隔秒精度) 。

当应用程序调用 SQLSetDescField 来设置描述符的字段而不是调用 SQLSetDescRec 时,应用程序必须首先声明数据类型。 这样做时,将隐式设置上表中指示的其他字段。 如果隐式设置的任何值是不可接受的,则应用程序可以调用 SQLSetDescFieldSQLSetDescRec 显式设置不可接受的值。

SQL_DESC_TYPE_NAME [实现描述符]
此只读 SQLCHAR * 记录字段包含数据源依赖类型名称 (,例如“CHAR”、“VARCHAR”等) 。 如果数据类型名称未知,此变量包含空字符串。

SQL_DESC_UNNAMED [实现描述符]
行描述符中的此 SQLSMALLINT 记录字段由驱动程序设置为SQL_NAMED或SQL_UNNAMED设置SQL_DESC_NAME字段时。 如果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 [IRD]
此只读 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 中的“一致性检查”。

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

另请参阅

ODBC 头文件
ODBC API 参考