SQLBindCol -将列绑定到应用程序变量

在线编辑

SQLBindCol() 用于将结果集中的列与所有数据类型的应用程序变量 (存储缓冲区) 相关联 (绑定)。 在调用 SQLFetch() 时，会将数据从数据库管理系统 (DBMS) 传输到应用程序。

此函数还用于指定所需的任何数据转换。 对应用程序需要检索的结果集中的每个列调用一次。

通常在此函数之前调用 SQLPrepare() 或 SQLExecDirect() 。 可能还需要调用 SQLDescribeCol() 或 SQLColAttribute() 以获取相应结果集列的属性。

必须在 SQLFetch() 之前调用 SQLBindCol() ，才能将数据传输到此调用指定的存储缓冲区。

语法

SQLRETURN SQLBindCol (SQLHSTMT       hstmt,
                      SQLSMALLINT    icol,
                      SQLSMALLINT    fCType,
                      SQLPOINTER     rgbValue,
                      SQLINTEGER     cbValueMax,
                      SQLINTEGER     *pcbValue);

函数自变量

表 1. SQLBindCol 自变量
数据类型 自变量 使用 描述
SQLHSTMT hstmt 输入 语句句柄。
SQLSMALLINT 冰醇 输入 标识列的编号。 从左到右按顺序对列进行编号，从 1 开始。
SQLSMALLINT fCType 输入 结果集中列号 icol 的应用程序数据类型。 支持以下类型:
  • SQL_C_BIGINT
  • SQL_C_BINARY
  • SQL_C_BLOB
  • sql_c_blob_locator
  • 开始更改SQL_C_BOOLEAN结束更改
  • SQL_C_CHAR
  • SQL_C_CLOB
  • sql_c_clob_locator
  • SQL_C_DATE
  • SQL_TYPE_DATE
  • SQL_C_DATETIME
  • SQL_C_DBCHAR
  • SQL_C_DBCLOB
  • sql_c_dbclob_locator
  • SQL_C_DECFLOAT128
  • SQL_C_DECFLOAT64
  • SQL_C_DECFLOAT32
  • SQL_C_DOUBLE
  • SQL_C_FLOAT
  • SQL_C_LONG
  • SQL_C_SLONG
  • SQL_C_REAL
  • SQL_C_SHORT
  • SQL_C_TIME
  • sql_c_timestamp
  • SQL_C_UTINYINT
  • SQL_TYPE_TIME
  • sql_type_timestamp
  • SQL_C_WCHAR
  • SQL_VARCHAR
  • SQL_WVARCHAR
  • SQL_VARGRAPHIC

指定 SQL_DEFAULT 会导致将数据传输到其缺省数据类型; 请参阅 表 1 以获取更多信息。

在许多情况下， SQL 数据类型常量 (例如 SQL_DECIMAL) 也可能用于应用程序数据类型。
SQLPOINTER rgbValue 输出 (延迟) 指向缓冲区的指针，Db2 for i CLI 将在获取时存储列数据。

如果 rgbValue 为空，那么该列未绑定。
SQLINTEGER cbValueMax 输入 可用于存储列数据的 rgbValue 缓冲区的大小 (以字节计)。

如果 fCType 是 SQL_CHAR 或 SQL_DEFAULT，则 cbValueMax 必须 > 0，否则将返回错误。

如果 fCType 指定 SQL_VARCHAR、SQL_WVARCHAR 或 SQL_VARGRAPHIC，cbValueMax 表示要返回的最大字符数。 由于 CLI 在前两个字节中返回这些类型的长度，因此 rgbValue 中指定的缓冲区大小必须比 cbValueMax 指定的长度大 2 个字节。 例如，如果类型是 SQL_VARCHAR，cbValueMax 是 10，那么缓冲区的长度至少应为 12 字节。 如果类型为 SQL_WVARCHAR，且 cbValueMax 为 10，则缓冲区长度至少应为 22 字节。

如果 fCType 是 SQL_DECIMAL 或 SQL_NUMERIC，cbValueMax 实际上必须是精度和比例。 指定这两个值的方法是使用 (precision * 256) + scale。 这也是使用 SQLColAttribute()时作为这些数据类型的 LENGTH 返回的值。

如果 fCType 是 SQL_C_TIMESTAMP 或 SQL_TYPE_TIMESTAMP，精度将基于 cbValueMax 的值。 当 cbValueMax 在 20 和 32 之间时，精度将为 cbValueMax - 20。 当 cbValueMax 小于 20 时，精度将为 0。 当 cbValueMax 大于 32 时，精度将为 12。

如果 fcType 指定了任何形式的双字节字符数据，那么 cbValueMax 必须是双字节字符数，而不是字节数。
SQLINTEGER * pcbValue 输出 (延迟) 指向值的指针，该值指示可在 rgbValue 缓冲区中返回的字节数 Db2 for i CLI。

如果列的数据值为空，那么 SQLFetch() 将在此自变量中返回 SQL_NULL_DATA 。 如果将列的数据值作为以 null 结束的字符串返回，那么将在此自变量中返回 SQL_NTS。
注：

对于此函数， rgbValue 和 pcbValue 都是延迟输出，这意味着在调用 SQLFetch() 之前不会更新这些指针指向的存储位置。 这些指针所引用的位置必须保持有效，直到调用 SQLFetch() 为止。

用法

应用程序对其要检索的结果集中的每个列调用 SQLBindCol() 一次。 调用 SQLFetch() 时，这些 界限 列中的每个列中的数据都放置在分配的位置 (由指针 rgbValue 和 pcbValue提供)。

应用程序可以通过首先调用 SQLDescribeCol() 或 SQLColAttribute()来查询列的属性 (例如数据类型和长度)。 然后，可以使用此信息来指定存储位置的正确数据类型，或者指示将数据转换为其他数据类型。 有关详细信息，请参阅 Db2 for i CLI 函数中的数据类型和数据转换。

对于后续访存请求，应用程序可以通过调用 SQLBindCol()来更改这些列的绑定或绑定未绑定的列。 新绑定不适用于访存的数据，将在调用下一个 SQLFetch() 时使用。 要取消单个列的绑定，请在 rgbValue 设置为 NULL 的情况下调用 SQLBindCol() 。 要取消所有列的绑定，应用程序应在 fOption 输入设置为 SQL_UNBIND 的情况下调用 SQLFreeStmt() 。

列由数字标识，从左到右按顺序分配，从 1 开始显示在结果集中。 可以通过调用 SQLNumResultCols() 或 SQLColAttribute() 并将 FieldIdentifier 自变量设置为 SQL_DESC_COUNT 来确定结果集中的列数。

如果 SQL_ATTR_UTF8 环境属性未设置为 SQL_TRUE ，那么所有字符数据都将被视为缺省作业编码字符集标识 (CCSID)。

应用程序可以选择将任何位置从零列绑定到所有列。 在调用 SQLFetch() 之后，可以使用 SQLGetData() 来检索未绑定列 (并且只能使用未绑定列) 中的数据。 SQLBindCol() 比 SQLGetData()更高效，应该尽可能使用。

应用程序必须确保为要检索的数据分配足够的存储空间。 如果缓冲区要包含可变长度数据，那么应用程序必须根据绑定列的最大长度分配所需的存储空间; 否则，数据可能会被截断。

对于输出字符串，缺省值为 null 终止。 要更改此值，必须将 SQLSetEnvAttr() 属性 SQL_ATTR_OUTPUT_NTS 设置为 SQL_FALSE。 在调用 SQLFetch() 之后， pcbValue 的输出值对于字符数据类型的行为方式如下所示:
  • 如果 SQL_ATTR_OUTPUT_NTS 属性设置为 SQL_TRUE (缺省值) ，那么将在 pcbValue中返回 SQL_NTS。
  • 如果 SQL_ATTR_OUTPUT_NTS 属性设置为 SQL_FALSE，那么 cbValueMax 的值，即可用的最大字节数，将在 pcbValue 中返回。
  • 如果发生截断，那么 cbValueMax 的值，即实际可用字节数，将在 pcbValue 中返回。

如果发生截断，并且 SQLSetEnvAttr() 属性 SQL_ATTR_TRUNCATION_RTNC 设置为 SQL_FALSE (这是缺省值) ，那么将在 SQLFetch() 返回码中返回 SQL_SUCCESS。 如果发生截断，并且属性为 SQL_TRUE ，那么将返回 SQL_SUCCESS_WITH_INFO。 如果未发生截断，那么在这两种情况下都将返回 SQL_SUCCESS。

当参数 cbValueMax 未为获取的数据量分配空间时，就会发生截断。 如果环境设置为以空字符结束的字符串运行，请确保为 cbValueMax 中的额外字节分配空间。 有关截断的其他信息，请参阅 SQLFetch - 取下一行。

Db2 for i CLI 与 DB2® CLI for Linux®， UNIX ， and Windows 的不同之处在于它在 pcbValue 自变量中返回长度信息的方式。 在访存 SQL_VARCHAR 列之后， Db2 for i CLI 将返回已绑定的 VARCHAR 结构的前 2 个字节中访存的字节。 Db2 for i CLI 不会像对 SQL_CHAR 那样返回 pcbValue 中的长度。 这与 DB2 CLI for Linux， UNIX ， and Windows 不同，后者没有 C VARCHAR 表示，并在应用程序绑定到 SQL_CHAR 列时包含 pcbValue 缓冲区中的长度信息。

对于十进制浮点数据类型，可以使用缺省符号 C 数据类型常量来指定精度 32,64 或 128。 例如，要指定精度为 128 字节的十进制浮点数据类型，可以将 fCType 设置为 SQL_C_DECIMAL128。

返回码

  • SQL_SUCCESS
  • SQL_ERROR
  • sql_invalid_handle

诊断

表 2。 SQLBindCol SQLSTATEs
SQLSTATE 描述 说明
40003 * 语句完成未知 在该功能完成处理之前， CLI 与数据源之间的通信链路发生故障。
58004 系统错误 不可恢复的系统错误。
HY001 内存分配失败 驱动程序无法分配支持功能处理或完成所需的内存。
HY002 无效的列号 为自变量 icol 指定的值为 0。

为自变量 icol 指定的值超过了数据源支持的最大列数。
HY003 程序类型超出范围 fCType 不是有效的数据类型。
HY009 参数值无效 rgbValue 是空指针。

为参数 cbValueMax 指定的值小于 1，并且参数 fCType 是 SQL_CHAR 或 SQL_DEFAULT。
HY013 * 内存管理问题 驱动程序无法访问支持处理或完成功能所需的内存。
HY014 句柄过多 已分配最大句柄数，使用此函数需要额外的描述符句柄。
HY021 内部描述符无效 无法寻址或分配内部描述符，或者它包含无效的值。
HYC00 驱动程序不支持 驱动程序识别，但不支持自变量 fCType 中指定的数据类型 (另请参阅 HY003)。

示例

请参阅 SQLFetch - 取下一行中的示例。

引用