SQLPutData 函数 (CLI)-传递参数的数据值

以片段形式发送大型参数值。在返回 SQL_NEED_DATA 以提供参数数据值的 SQLParamData() 调用之后调用 SQLPutData() 。

规范：

CLI 2.1
ODBC 1.0
ISO CLI

语法

SQLRETURN   SQLPutData       (
               SQLHSTMT          StatementHandle,   /* hstmt */
               SQLPOINTER        DataPtr,           /* rgbValue */
               SQLLEN            StrLen_or_Ind);    /* cbValue */

函数参数

表 1. SQLPutData 自变量
数据类型	自变量	使用	描述
SQLHSTMT	StatementHandle	输入	语句句柄。
SQLPOINTER	DataPtr	输入	指向参数的实际数据或部分数据的指针。数据必须采用应用程序在指定参数时使用的 SQLBindParameter() 调用中指定的格式。
SQLLEN	字符串或输入	输入	DataPtr的长度。指定在对 SQLPutData() 的调用中发送的数据量。对于给定参数的每个调用，数据量可能有所不同。应用程序还可以为 StrLen_or_Ind指定 SQL_NTS 或 SQL_NULL_DATA。对于所有固定长度 C 缓冲区类型 (例如，日期，时间，时间戳记和所有数字 C 缓冲区类型) ，将忽略 StrLen_or_Ind 。对于 C 缓冲区类型为 SQL_C_CHAR 或 SQL_C_BINARY 的情况，或者如果将 SQL_C_DEFAULT 指定为 C 缓冲区类型并且 C 缓冲区类型缺省值为 SQL_C_CHAR 或 SQL_C_BINARY ，那么这是 DataPtr 缓冲区中的数据字节数。

用法

应用程序在对处于 SQL_NEED_DATA 状态的语句调用 SQLParamData() 之后调用 SQLPutData() ，以提供 SQL_DATA_AT_EXEC 参数的数据值。可以通过对 SQLPutData()的重复调用将长整型数据分批发送。 CLI 为每个 SQL_DATA_AT_EXEC 参数生成一个临时文件，调用 SQLPutData() 时，会将每个数据段追加到该文件中。可以使用 db2cli.ini 文件中的 TEMPDIR 关键字来设置 CLI 创建其临时文件的路径。如果未设置此关键字，那么 CLI 会尝试写入环境变量 TEMP 或 TMP 指定的路径。在发送该参数的所有数据段之后，应用程序再次调用 SQLParamData() 以继续执行下一个 SQL_DATA_AT_EXEC 参数，或者如果所有参数都具有数据值，那么执行该语句。

对于固定长度的 C 缓冲区类型 (例如 SQL_C_LONG) ，不能多次调用 SQLPutData() 。

在 SQLPutData() 调用之后，如果输入数据是字符或二进制数据，那么唯一的合法函数调用是 SQLParamData()， SQLCancel()或其他 SQLPutData() 。与 SQLParamData()一样，使用此语句句柄的所有其他函数调用都将失败。此外，如果引用 StatementHandle 的父连接句柄的所有函数调用涉及更改该连接的任何属性或状态，那么这些函数调用将失败; 即，也不允许对父连接句柄进行以下函数调用:

SQLSetConnectAttr ()
SQLEndTran()

但是，当设置了 SQL_ATTR_FORCE_ROLLBACK 连接属性，将 StreamPut数据配置关键字设置为 1 并启用自动落实方式时，允许调用指定 SQL_ROLLBACK 作为完成类型的 SQLEndTran() 函数。

如果在 SQL_NEED_DATA 序列期间调用这些函数，那么这些函数将返回 SQL_ERROR ， SQLSTATE 为 HY010 ，并且 SQL_DATA_AT_EXEC 参数的处理将不受影响。

如果针对单个参数对 SQLPutData() 的一个或多个调用导致 SQL_SUCCESS ，那么尝试在将 StrLen_or_Ind 设置为 SQL_NULL_DATA 的情况下对同一参数调用 SQLPutData() 会导致 SQLSTATE 为 22005 的错误。此错误不会导致状态更改; 语句句柄仍处于需要数据状态，并且应用程序可以继续发送参数数据。

返回码

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_STILL_正在执行
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

以下某些诊断条件也可能在最终 SQLParamData() 调用时报告，而不是在调用 SQLPutData() 时报告。

表 2. SQLPutData SQLSTAT
SQLSTATE	描述	说明
01004	数据被截断。	为数字参数发送的数据被截断而不丢失有效数字。为日期或时间列发送的时间戳记数据已截断。函数返回 SQL_SUCCESS_WITH_INFO。
22001	字符串数据右截断。	针对二进制或字符数据发送的数据超过了数据源对该列的支持。
22003	数值超出范围。	为数字参数发送的数据在分配给关联列时导致数字的整个部分被截断。对固定长度参数多次调用了 SQLPutData() 。
22005	赋值错误。	为参数发送的数据与关联表列的数据类型不兼容。
22007	日期时间格式无效。	为日期，时间或时间戳记参数发送的数据值无效。
40003 08S01	通信链路故障。	在功能完成之前，应用程序与数据源之间的通信链路失败。
HY001	内存分配故障。	Db2® CLI 无法分配支持执行或完成该功能所需的内存。应用程序进程有可能已用完进程级内存。请参阅操作系统配置以获取有关进程级别内存限制的信息。
HY008	已取消操作。	已对 StatementHandle启用异步处理。已调用该函数，并且在该函数完成执行之前，已从多线程应用程序中的另一个线程在 StatementHandle 上调用了 `SQLCancel()` 。然后，在 StatementHandle上再次调用该函数。
HY009	参数值无效。	自变量 DataPtr 是 NULL 指针，而自变量 StrLen_or_Ind 既不是 0 也不是 SQL_NULL_DATA。
HY010	函数顺序错误。	语句句柄 StatementHandle 必须处于需要的数据状态，并且必须已通过先前的 SQLParamData() 调用定位在 SQL_DATA_AT_EXEC 参数上。
HY090	字符串或缓冲区长度无效。	自变量 DataPtr 不是 NULL 指针，并且自变量 StrLen_or_Ind 小于 0 ，但不等于 SQL_NTS 或 SQL_NULL_DATA。
HYT00	超时已到期。	在数据源返回结果集之前，超时时间段已到期。可以使用 `SQLSetStmtAttr()`的 SQL_ATTR_QUERY_TIMEOUT 属性来设置超时时间段。注: 此 SQLSTATE 仅适用于 .Net 应用程序。

限制

在 ODBC 2.0中引入了 StrLen_or_IndSQL_DEFAULT_PARAM 的附加值，以指示过程将使用参数的缺省值，而不是从应用程序发送的值。由于 Db2 存储过程自变量不支持缺省值，因此对 StrLen_or_Ind 自变量指定此值将导致在执行 CALL 语句时发生错误，因为 SQL_DEFAULT_PARAM 值将被视为无效长度。

ODBC 2.0 还引入了要与 StrLen_or_Ind 自变量配合使用的 SQL_LEN_DATA_AT_EXEC (length) 宏。宏用于指定将通过后续 SQLPutData() 调用为字符或二进制 C 数据发送的整个数据的总长度总和。由于 Db2 ODBC 驱动程序不需要此信息，因此不需要宏。 ODBC 应用程序使用 SQL_NEED_LONG_DATA_LEN 选项调用 SQLGetInfo() 以检查驱动程序是否需要此信息。 Db2 ODBC 驱动程序将返回 "N" 以指示 SQLPutData()不需要此信息。

示例

  SQLCHAR buffer[BUFSIZ];
  size_t n = BUFSIZ;

  /* ... */
  
  /* passing data value for a parameter */
  cliRC = SQLPutData(hstmt, buffer, n);