SQLBindParameter －将参数标记绑定至缓冲区

用途

规范：

DB2 CLI 2.1

ODBC 2.0

对于所有 C 数据类型，SQLBindParameter() 用来使 SQL 语句中的参数标记与应用程序变量相关联（绑定）。在这种情况下，调用 SQLExecute() 或 SQLExecDirect() 时，数据是从应用程序传送至 DBMS 的。传送数据时，可能会发生数据转换。

语法

SQLRETURN  SQL_API SQLBindParameter(
                  SQLHSTMT          StatementHandle,  /* hstmt */
                SQLUSMALLINT      ParameterNumber,  /* ipar */
                SQLSMALLINT       InputOutputType,  /* fParamType */
                SQLSMALLINT       ValueType,        /* fCType */
                SQLSMALLINT       ParameterType,    /* fSqlType */
                SQLUINTEGER       ColumnSize,       /* cbColDef */
                SQLSMALLINT       DecimalDigits,    /* ibScale */
                SQLPOINTER        ParameterValuePtr,/* rgbValue */
                SQLINTEGER        BufferLength,      /* cbValueMax */
                SQLINTEGER *FAR   StrLen_or_IndPtr);/* pcbValue */

函数自变量

表 34. SQLBindParameter 自变量

数据类型	自变量	使用	描述
SQLHSTMT	`StatementHandle`	输入	语句句柄。
SQLUSMALLINT	`ParameterNumber`	输入	参数标记号码从左到右，从 1 开始依次编号。
SQLSMALLINT	`InputOutputType`	输入	参数类型。支持的类型是： SQL_PARAM_INPUT：执行此语句时，参数的实际数据值被发送至服务器；ParameterValuePtr 缓冲区必须包含有效的输入数据值，而 `StrLen_or_IndPtr` 缓冲区必须包含相应的长度值，或者 SQL_NTS 或 SQL_NULL_DATA。 DB2 Everyplace 不支持 `SQLPutData()`，所以不应将参数值存储在 ParameterValuePtr 缓冲区中。 SQL_PARAM_INPUT_OUTPUT：参数标记与所调用的存储过程的输入／输出参数相关联。执行语句时，参数的实际数据值被送至服务器。`ParameterValuePtr` 缓冲区必须包含有效的输入数据值；`StrLen_or_IndPtr` 缓冲区必须包含相应的长度值或 SQL_NTS、SQL_NULL_DATA。 SQL_PARAM_OUTPUT：参数标记与所调用的存储过程的输出参数或者该存储过程的返回值相关联。执行该语句之后，输出参数的数据被返回到由 `ParameterValuePtr` 和 `StrLen_or_IndPtr` 指定的应用程序缓冲区中，除非这两个指针都是空指针，在这种情况下，输出数据将被废弃。如果输出参数没有返回值，则 `StrLen_or_IndPtr` 被设置为 SQL_NULL_DATA。
SQLSMALLINT	`ValueType`	输入	参数的 C 数据类型。下列类型受支持： SQL_C_BINARY SQL_C_BIT SQL_C_CHAR SQL_C_DOUBLE SQL_C_FLOAT SQL_C_LONG SQL_C_SHORT SQL_C_TYPE_DATE SQL_C_TYPE_TIME SQL_C_TYPE_TIMESTAMP SQL_C_TINYINT 指定 SQL_C_DEFAULT 会导致将数据从其缺省 C 数据类型转换为 `ParameterType` 中指示的类型。
SQLSMALLINT	`ParameterType`	输入	参数的 SQL 数据类型。支持的类型是： SQL_BLOB SQL_CHAR SQL_DECIMAL SQL_INTEGER SQL_SMALLINT SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_VARCHAR
SQLUINTEGER	`ColumnSize`	输入	对应的参数标记的精度。如果 `ParameterType` 指示二进制或单字节字符串（如 SQL_CHAR、SQL_BLOB），则这是此参数标记的最大长度（以字节计）。否则，此自变量被忽略。
SQLSMALLINT	`DecimalDigits`	输入	（相应参数的小数位数）如果 `ParameterType` 是 SQL_DECIMAL。
SQLPOINTER	`ParameterValuePtr`	输入（延迟）和／或输出（延迟）	在输入时（`InputOutputType` 设置为 SQL_PARAM_INPUT 或 SQL_PARAM_INPUT_OUTPUT）：在执行时，如果 `StrLen_or_IndPtr` 未包含 SQL_NULL_DATA，则 `ParameterValuePtr` 指向包含参数实际数据的缓冲区。在输出时（InputOutputType 设置为 SQL_PARAM_OUTPUT 或 SQL_PARAM_INPUT_OUTPUT）：`ParameterValuePtr` 指向存储存储过程的输出参数值的缓冲区。空 `ParameterValuePtr` 指示取消绑定参数。
SQLINTEGER	`BufferLength`	输入	对于字符和二进制数据，`BufferLength` 指定 `ParameterValuePtr` 缓冲区的长度。对于非字符和非二进制数据，此自变量被忽略，且 `ParameterValuePtr` 缓冲区的长度被假定为与 C 数据类型相关联的长度。对于输出参数，`BufferLength` 被用来确定是否截断数据。
SQLINTEGER *	`StrLen_or_IndPtr`	输入（延迟）和／或输出（延迟）	如果这是输入或输入／输出参数：这是指向（在执行语句时）包含在 `ParameterValuePtr` 处存储的参数标记值长度的位置的指针。要对参数标记符指定空值，此存储位置必须包含 SQL_NULL_DATA。如果 `ValueType` 是 SQL_C_CHAR，则此存储位置必须包含在 `ParameterValuePtr` 处存储的数据的精确长度，或包含 SQL_NTS（如果 `ParameterValuePtr` 处的内容以 null 结束的话）。如果它包含确切的长度，则存储在 ParameterValuePtr 处的数据中不允许空字符。如果 `ValueType` 指示字符数据（显式指定或使用 SQL_C_DEFAULT 隐式指定），且此指针设置为 NULL，则应用程序必须在 `ParameterValuePtr` 中提供以 null 结束的字符串。这也表示此参数标记永远不会具有空值。如果这是输出参数（`InputOutputType` 设置为 SQL_PARAM_OUTPUT）：在执行存储过程之后，这必须是存储过程 CALL 的输出参数或返回值，并且必须指向下列其中一项：可在 `ParameterValuePtr` 中返回的字节数（null 终止字符除外）。 SQL_NULL_DATA

用法

在 SQL 语句中，参数标记由 ? 字符表示，用来指示语句中的一个位置，在该处，应用程序提供的值将在执行该语句时被替换。此值可以从应用程序变量获取。SQLBindParameter() 用来将应用程序存储区与参数标记绑定。

在执行 SQL 语句之前，应用程序必须将一个变量与 SQL 语句中的每个参数标记绑定。对于此函数，ParameterValuePtr 和 StrLen_or_IndPtr 是延迟自变量。执行该语句时，存储位置必须有效且包含输入数据值。这表示 SQLExecDirect() 或 SQLExecute() 调用都必须保存在与 SQLBindParameter() 调用相同的过程作用域中，或者这些存储位置必须是动态分配的，或是以静态方式或全局方式声明的。

参数标记按编号（ColumnNumber）引用，并且是从 1 开始从左到右按顺序编号的。

在调用下列其中一个函数之前，此函数绑定的所有参数仍然有效：

调用 SQLFreeStmt()，并指定 SQL_RESET_PARAMS 选项。
调用 SQLFreeHandle()，并将 HandleType 设置为 SQL_HANDLE_STMT。
再次对同一参数 ParameterNumber 编号调用 SQLBindParameter()。

在执行 SQL 语句并处理结果之后，应用程序可能想重新使用该语句句柄来执行另一 SQL 语句。如果参数标记规范不同（参数数目、长度或类型不同），则必须使用 SQL_RESET_PARAMS 调用 SQLFreeStmt()，以复位或清除参数绑定。

ValueType 给出的 C 缓冲区数据类型必须与 ParameterType 指示的 SQL 数据类型相兼容，否则会出错。

因为在执行语句之前，不会验证 ParameterValuePtr 和 StrLen_or_IndPtr 所引用的变量中的数据，所以在调用 SQLExecute() 或 SQLExecDirect() 之前，不会检测或报告数据内容错误或格式错误。

对于此函数，ParameterValuePtr 和 StrLen_or_IndPtr 是延迟自变量。在 InputOutputType 设置为 SQL_PARAM_INPUT 的情况下，当执行语句时，存储位置必须有效且包含输入数据值。这表示 SQLExecDirect() 或 SQLExecute() 调用都必须保存在与 SQLBindParameter() 调用相同的过程作用域中，或者这些存储位置必须是动态分配的，或是以静态方式或全局方式声明的。

DB2 Everyplace 支持 SQL_PARAM_INPUT、SQL_PARAM_INPUT_OUTPUT 和 SQL_PARAM_OUTPUT。DB2 Everyplace 不支持 SQLPutData()，所以不应将参数值存储在 ParameterValuePtr 缓冲区中。

对于字符和二进制 C 数据，BufferLength 自变量指定 ParameterValuePtr 缓冲区的长度。对于所有其它类型的 C 数据，BufferLength 自变量被忽略。

返回码

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

诊断

表 35. SQLBindParameter SQLSTATE

SQLSTATE	描述	解释
07006	转换无效。	从 `ValueType` 自变量标识的数据值到 `ParameterType` 自变量标识的数据类型的转换不是有意义的转换。（例如，从 SQL_C_DATE 转换至 SQL_DOUBLE。）
40003 08S01	通信链路故障。	函数尚未完成，应用程序与数据源间的通信链路就失效了。
58004	意外系统故障。	不可恢复的系统错误。
HY001	内存分配失败。	DB2 CLI 无法分配支持函数的执行或完成所需的内存。
HY003	程序类型超出范围。	`ParameterNumber` 自变量指定的值不是有效的数据类型或 SQL_C_DEFAULT。
HY004	SQL 数据类型超出范围。	对 `ParameterType` 自变量指定的值不是有效的 SQL 数据类型。
HY009	自变量值无效。	`ParameterValuePtr` 自变量是空指针，且 `StrLen_or_IndPtr` 自变量是空指针，而 `InputOutputType` 不是 SQL_PARAM_OUTPUT。
HY013	发生意外的内存处理错误。	DB2 CLI 无法访问支持函数的执行或完成所需的内存。
HY090	字符串或缓冲区长度无效。	对 `BufferLength` 自变量指定的值小于 0。
HY093	参数号无效。	对 `ValueType` 自变量指定的值小于 1 或大于服务器支持的最大参数数目。
HY094	小数位值无效。	对 `ParameterType` 指定的值是 SQL_DECIMAL 或 SQL_NUMERIC，对 `DecimalDigits` 指定的值小于 0 或大于 `ParamDef` 自变量（精度）的值。
HY104	精度值无效。	对 `ParameterType` 指定的值是 SQL_DECIMAL 或 SQL_NUMERIC，对 `ParamDef` 指定的值小于 1。
HY105	参数类型无效。	`InputOutputType` 不是 SQL_PARAM_INPUT。
HYC00	驱动程序不起作用。	DB2 CLI 或数据源不支持由对 `ValueType` 自变量指定的值和对 `ParameterType` 祖变量指定的值的组合所指定的转换。对 `ParameterType` 自变量指定的值不受 DB2 CLI 或数据源支持。

相关参考

SQLBindParameter － 将参数标记绑定至缓冲区

SQLBindParameter －将参数标记绑定至缓冲区