SQLBindParam - Bind a buffer to a parameter marker

 

SQLBindParam() has been deprecated and replaced by SQLBindParameter(). Although this version of DB2® UDB CLI continues to support SQLBindParam(), it is recommended that you begin using SQLBindParameter() in your DB2 UDB CLI programs so that they conform to the latest standards.

SQLBindParam() binds an application variable to a parameter marker in an SQL statement. This function can also be used to bind an application variable to a parameter of a stored procedure CALL statement where the parameter can be input or output.

 

Syntax

SQLRETURN SQLBindParam (SQLHSTMT    hstmt,
                        SQLSMALLINT ipar,
                        SQLSMALLINT fCType,
                        SQLSMALLINT fSqlType,
                        SQLINTEGER  cbParamDef,
                        SQLSMALLINT ibScale,
                        SQLPOINTER  rgbValue,
                        SQLINTEGER  *pcbValue);

 

Function arguments

Table 1. SQLBindParam arguments
Data type Argument Use Description
SQLHSTMT hstmt Input Statement handle.
SQLSMALLINT ipar Input Parameter marker number, ordered sequentially left to right, starting at 1.
SQLSMALLINT fCType Input Application data type of the parameter. The following types are supported:

  • SQL_BIGINT

  • SQL_BINARY

  • SQL_BLOB

  • SQL_BLOB_LOCATOR

  • SQL_CHAR

  • SQL_CLOB

  • SQL_CLOB_LOCATOR

  • SQL_DATETIME

  • SQL_DBCLOB

  • SQL_DBCLOB_LOCATOR

  • SQL_DECIMAL

  • SQL_DOUBLE

  • SQL_FLOAT

  • SQL_GRAPHIC

  • SQL_INTEGER

  • SQL_NUMERIC

  • SQL_REAL

  • SQL_SMALLINT

  • SQL_TYPE_DATE

  • SQL_TYPE_TIME

  • SQL_TYPE_TIMESTAMP

  • SQL_VARBINARY

  • SQL_VARCHAR

  • SQL_VARGRAPHIC

  • SQL_WCHAR

  • SQL_WVARCHAR

Specifying SQL_DEFAULT causes data to be transferred from its default application data type to the type indicated in fSqlType.

SQLSMALLINT fSqlType Input SQL data type of the parameter. The supported types are:

  • SQL_BIGINT

  • SQL_BINARY

  • SQL_BLOB

  • SQL_BLOB_LOCATOR

  • SQL_CHAR

  • SQL_CLOB

  • SQL_CLOB_LOCATOR

  • SQL_DATETIME

  • SQL_DBCLOB

  • SQL_DBCLOB_LOCATOR

  • SQL_DECIMAL

  • SQL_DOUBLE

  • SQL_FLOAT

  • SQL_GRAPHIC

  • SQL_INTEGER

  • SQL_NUMERIC

  • SQL_REAL

  • SQL_SMALLINT

  • SQL_TYPE_DATE

  • SQL_TYPE_TIME

  • SQL_TYPE_TIMESTAMP

  • SQL_VARBINARY

  • SQL_VARCHAR

  • SQL_VARGRAPHIC

  • SQL_WCHAR

  • SQL_WVARCHAR
SQLINTEGER cbParamDef Input Precision of the corresponding parameter marker.

  • If fSqlType denotes a single-byte character string (for example, SQL_CHAR), this is the maximum length in bytes sent for this parameter. This length includes the null-termination character.

  • If fSqlType denotes a double-byte character string (for example, SQL_GRAPHIC), this is the maximum length in double-byte characters for this parameter.

  • If fSqlType denotes SQL_DECIMAL or SQL_NUMERIC, this is the maximum decimal precision.

  • Otherwise, this argument is unused.
SQLSMALLINT ibScale Input Scale of the corresponding parameter if fSqlType is SQL_DECIMAL or SQL_NUMERIC. If fSqlType is SQL_TIMESTAMP, this is the number of digits to the right of the decimal point in the character representation of a timestamp (for example, the scale of yyyy-mm-dd hh:mm:ss.fff is 3).

Other than for the fSqlType values mentioned here, ibScale is unused.

SQLPOINTER rgbValue

Input (deferred)
or
output (deferred)

At processing time, if pcbValue does not contain SQL_NULL_DATA or SQL_DATA_AT_EXEC, then rgbValue points to a buffer that contains the actual data for the parameter.

If pcbValue contains SQL_DATA_AT_EXEC, then rgbValue is an application-defined 32-bit value that is associated with this parameter. This 32-bit value is returned to the application through a later SQLParamData() call.

SQLINTEGER * pcbValue Input (deferred), or output (deferred), or both A variable whose value is interpreted when the statement is processed:

  • If a null value is used as the parameter, pcbValue must contain the value SQL_NULL_DATA.

  • If the dynamic argument is supplied at execute-time by calling ParamData() and PutData(), pcbValue must contain the value SQL_DATA_AT_EXEC.

  • If fcType is SQL_CHAR and the data in rgbValue contains a null-terminated string, pcbValue must either contain the length of the data in rgbValue or contain the value SQL_NTS.

  • If fcType is SQL_CHAR and the data in rgbValue is not null-terminated, pcbValue must contain the length of the data in rgbValue.

  • If fcType is a LOB type, pcbValue must contain the length of the data in rgbValue. This length value must be specified in bytes, not the number of double byte characters.

  • Otherwise, pcbValue must be zero.

 

Usage

When SQLBindParam() is used to bind an application variable to an output parameter for a stored procedure, DB2 UDB CLI provides some performance enhancement if the rgbValue buffer is placed consecutively in memory after the pcbValue buffer.

 

Return codes

 

Diagnostics

Table 2. SQLBindParam SQLSTATEs
SQLSTATE Description Explanation
07006 Restricted data type attribute violation Same as SQLSetParam().
40003 * Statement completion unknown The communication link between the CLI and the data source fails before the function completes processing.
58004 System error Unrecoverable system error.
HY001 Memory allocation failure The driver is unable to allocate memory required to support the processing or completion of the function.
HY003 Program type out of range Same as SQLSetParam().
HY004 SQL data type out of range Same as SQLSetParam().
HY009 Argument value that is not valid Both rgbValue and pcbValue are null pointers, or ipar is less than one.
HY010 Function sequence error Function is called after SQLExecute() or SQLExecDirect() has returned SQL_NEED_DATA, but data has not been sent for all data-at-execution parameters.
HY013 * Memory management problem The driver is unable to access memory required to support the processing or completion of the function.
HY014 Too many handles The maximum number of handles has been allocated.
HY021 Internal descriptor that is not valid The internal descriptor cannot be addressed or allocated, or it contains a value that is not valid.

 

References

SQLBindParameter - Bind a parameter marker to a buffer

 

Parent topic:

DB2 UDB CLI functions