`SQLBindParameter()` - Bind a parameter marker to a buffer or LOB locator

SQLBindParameter() binds parameter markers to application variables and extends the capability of the SQLSetParam() function.

ODBC specifications for `SQLBindParameter()`

Table 1. `SQLBindParameter()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
2.0	No	No

Syntax

For 31-bit applications, use the following syntax:

SQLRETURN  SQL_API SQLBindParameter(
                              SQLHSTMT          hstmt,
                              SQLUSMALLINT      ipar,
                              SQLSMALLINT       fParamType,
                              SQLSMALLINT       fCType,
                              SQLSMALLINT       fSqlType,
                              SQLUINTEGER       cbColDef,
                              SQLSMALLINT       ibScale,
                              SQLPOINTER        rgbValue,
                              SQLINTEGER        cbValueMax,
                              SQLINTEGER   FAR *pcbValue);

For 64-bit applications, use the following syntax:

SQLRETURN  SQL_API SQLBindParameter(
                              SQLHSTMT          hstmt,
                              SQLUSMALLINT      ipar,
                              SQLSMALLINT       fParamType,
                              SQLSMALLINT       fCType,
                              SQLSMALLINT       fSqlType,
                              SQLULEN           cbColDef,
                              SQLSMALLINT       ibScale,
                              SQLPOINTER        rgbValue,
                              SQLLEN            cbValueMax,
                              SQLLEN       FAR *pcbValue);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. `SQLBindParameter()` arguments
Data type	Argument	Use	Description
SQLHSTMT	hstmt	input	Specifies the statement handle of the statement you bind.
SQLUSMALLINT	ipar	input	Specifies the parameter marker number, which are ordered sequentially left to right, starting at 1.
SQLSMALLINT	fParamType	input	Specifies the type of parameter. You can specify the following types of parameters: SQL_PARAM_INPUT: The parameter marker is associated with an SQL statement that is not a stored procedure CALL; or, it marks an input parameter of the called stored procedure. When the statement is executed, actual data value for the parameter is sent to the server: the rgbValue buffer must contain valid input data values; the pcbValue buffer must contain the corresponding length value, in bytes, or SQL_NTS, SQL_NULL_DATA, or (if the value should be sent using the `SQLParamData()` and `SQLPutData()` functions) SQL_DATA_AT_EXEC. SQL_PARAM_INPUT_OUTPUT: The parameter marker is associated with an input/output parameter of the called stored procedure. When the statement is executed, actual data value for the parameter is sent to the server: the rgbValue buffer must contain valid input data values; the pcbValue buffer must contain the corresponding length value, in bytes, or SQL_NTS, SQL_NULL_DATA, or, if the value should be sent using `SQLParamData()` and `SQLPutData()`, SQL_DATA_AT_EXEC. SQL_PARAM_OUTPUT: The parameter marker is associated with an output parameter of the called stored procedure or the return value of the stored procedure. After the statement is executed, data for the output parameter is returned to the application buffer specified by rgbValue and pcbValue, unless both are null pointers, in which case the output data is discarded.
SQLSMALLINT	fCType	input	Specifies the C data type of the parameter. The following types are supported: SQL_C_BIGINT SQL_C_BINARY SQL_C_BINARYXML SQL_C_BIT SQL_C_BLOB_LOCATOR SQL_C_CHAR SQL_C_CLOB_LOCATOR SQL_C_DBCHAR SQL_C_DBCLOB_LOCATOR SQL_C_DECIMAL64 SQL_C_DECIMAL128 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_TYPE_TIMESTAMP_EXT SQL_C_TYPE_TIMESTAMP_EXT_TZ SQL_C_TINYINT SQL_C_WCHAR Specifying SQL_C_DEFAULT causes data to be transferred from its default C data type to the type indicated in fSqlType.
SQLSMALLINT	fSqlType	input	Specifies the 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_DBCLOB SQL_DBCLOB_LOCATOR SQL_DECFLOAT SQL_DECIMAL SQL_DOUBLE SQL_FLOAT SQL_GRAPHIC SQL_INTEGER SQL_LONGVARBINARY SQL_LONGVARCHAR SQL_LONGVARGRAPHIC SQL_NUMERIC SQL_REAL SQL_ROWID SQL_SMALLINT SQL_TYPE_DATE SQL_TYPE_TIME SQL_TYPE_TIMESTAMP SQL_TYPE_TIMESTAMP_WITH_TIMEZONE SQL_VARBINARY SQL_VARCHAR SQL_VARGRAPHIC SQL_XML Restriction: SQL_BLOB_LOCATOR, SQL_CLOB_LOCATOR, and SQL_DBCLOB_LOCATOR are application related concepts and do not map to a data type for column definition during a CREATE TABLE.
SQLUINTEGER (31-bit) or SQLULEN (64-bit) ¹	cbColDef	input	Specifies the precision of the corresponding parameter marker. The meaning of this precision depends on what data type the fSqlType argument denotes: For a binary or single-byte character string (for example, SQL_CHAR, SQL_BINARY), this is the maximum length in bytes for this parameter marker. For a double-byte character string (for example, SQL_GRAPHIC), this is the maximum length in double-byte characters for this parameter. For SQL_DECIMAL, SQL_NUMERIC, this is the maximum decimal precision. For SQL_DECFLOAT, the cbColDef argument must specify the precision of the parameter marker, which is 16 if the column is DECFLOAT(16) or 34 if the column is DECFLOAT(34). For SQL_ROWID, this must be set to 40, the maximum length in bytes for this data type. Otherwise, an error is returned. Otherwise, this argument is ignored.
SQLSMALLINT	ibScale	input	Specifies the scale of the corresponding parameter if the fSqlType argument is SQL_DECIMAL or SQL_NUMERIC. If the fSqlType argument specifies SQL_TYPE_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 the values for the fSqlType argument that are mentioned here, the ibScale argument is ignored.
SQLPOINTER	rgbValue	input (deferred), output (deferred), or input (deferred) and output (deferred)	The following characteristics apply to the rgbValue argument depending on whether it is an input argument, an output argument, or both: As an input argument (when the fParamType argument specifies SQL_PARAM_INPUT, or SQL_PARAM_INPUT_OUTPUT), rgbValue exhibits the following behavior: At execution time, if the pcbValue argument 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 the `pcbValue` argument contains SQL_DATA_AT_EXEC, rgbValue is an application-defined 32-bit value that is associated with this parameter. This 32-bit value is returned to the application using a subsequent `SQLParamData()` call. If `SQLSetStmtAttr()` is called to specify multiple values for the parameter, then rgbValue is a pointer to an input buffer array of cbValueMax bytes. As an output argument (when the fParamType argument specifies SQL_PARAM_OUTPUT, or SQL_PARAM_INPUT_OUTPUT), the rgbValue argument points to the buffer where the output parameter value of the stored procedure is stored. If the fParamType argument is set to SQL_PARAM_OUTPUT, and both the rgbValue argument and the pcbValue argument specify null pointers, then the output parameter value or the return value from the stored procedure call is discarded.
SQLINTEGER (31-bit) or SQLLEN (64-bit) ²	cbValueMax	input	For character and binary data, the cbValueMax argument specifies the size, in bytes, of the buffer that the rgbValue argument indicates. If this buffer is a single element, this value specifies the size of that element. If this buffer is an array, the value specifies the size of each element in that array. Call `SQLSetStmtAttr()` to specify multiple values for each parameter. For non-character and non-binary data, this argument is ignored. This length is assumed to be the length that is associated with the C data type in these cases. For output parameters, the cbValueMax argument is used to determine whether to truncate character or binary output data. Data is truncated in the following manner: For character data, if the number of bytes available to return is greater than or equal to the value that the cbValueMax argument specifies, the data in the buffer to which the rgbValue argument points is truncated. This data is truncated to a length, in bytes, that is equivalent to the value that the cbValueMax argument specifies minus one byte. Truncated character data is nul-terminated (unless nul-termination has been turned off). For binary data, if the number of bytes available to return is greater than the value that the cbValueMax argument specifies, the data to which the rgbValue argument points is truncated. This data is truncated to a length, in bytes, that is equivalent to the value that the cbValueMax argument specifies.
SQLINTEGER * (31-bit) SQLLEN * (64-bit)²	pcbValue	input (deferred), output (deferred), or input (deferred) and output (deferred)	The following characteristics apply to the pcbValue argument depending on whether it is an input argument, an output argument, or both: As an input argument (when the fParamType argument specifies SQL_PARAM_INPUT, or SQL_PARAM_INPUT_OUTPUT), the pcbValue argument points to the buffer that contains the length, in bytes, of the parameter marker value (when the statement is executed) to which the rgbValue argument points. To specify a null value for a parameter marker, this storage location must contain SQL_NULL_DATA. If the fCType argument specifies SQL_C_CHAR or SQL_C_WCHAR, the buffer to which the pcbValue argument points must contain either the exact length (in bytes) of the data or SQL_NTS for nul-terminated strings. If the fCType argument indicates character data (explicitly, or implicitly with SQL_C_DEFAULT), and the pcbValue argument is set to NULL, it is assumed that the application always provides a nul-terminated string in the buffer to which the rgbValue argument points. This null setting also implies that the parameter marker never uses null values. If the fSqlType argument indicates a graphic data type and the fCType argument is set to SQL_C_CHAR, you cannot set the pcbValue argument to NULL or point the pcbValue argument to a buffer that holds the value SQL_NTS. In general, for graphic data types, the value this buffer holds is the number of bytes that the double-byte data occupies. Always specify a multiple of 2 for the length of double-byte data. If you specify a value that is odd, an error occurs when the statement is executed. When `SQLExecute()` or `SQLExecDirect()` is called, and the pcbValue argument points to a value of SQL_DATA_AT_EXEC, the data for the parameter is sent with `SQLPutData()`. This parameter is referred to as a data-at-execution parameter.
Continued SQLINTEGER * (31-bit) SQLLEN * (64-bit)²	pcbValue	input (deferred), output (deferred), or input (deferred) and output (deferred)	If you use `SQLSetStmtAttr()` to specify multiple values for each parameter, the pcbValue argument points to an array of SQLINTEGER values. Each element in this array specifies the number of bytes (excluding the nul-terminator) that correspond to elements in the array that the rgbValue specifies, or the value SQL_NULL_DATA. If you use `SQLBindParameter()`, you can specify values for SQL_UNASSIGNED and SQL_DEFAULT_PARAM in the `pcbValue` argument. These values require that you enable extended indicator support with the INI keyword EXTENDEDINDICATOR or the SQL_ATTR_EXTENDED_INDICATORS connection variable. If you specify SQL_UNASSIGNED or SQL_DEFAULT PARAM when extended indicator support is disabled, the results are the same as specifying SQL_NULL_DATA. SQL_DEFAULT_PARAM The target column of the bound parameter is set to its defined DEFAULT value. SQL_UNASSIGNED The target column of the bound parameter is ignored for UPDATE, and MERGE UPDATE operations. The parameter is handled the same way as the DEFAULT keyword for INSERT, and MERGE INSERT operations. As an output argument (when the fParamType argument is set to SQL_PARAM_OUTPUT, or SQL_PARAM_INPUT_OUTPUT), the pcbValue argument points to one of the following values, after the execution of the stored procedure: number of bytes available to return in rgbValue, excluding the nul-termination character. SQL_NULL_DATA SQL_NO_TOTAL if the number of bytes available to return cannot be determined.
Notes: For 64-bit applications, the data type SQLUINTEGER, which was used in previous versions of Db2, is still valid. However, for maximum application portability, using SQLULEN is recommended. For 64-bit applications, the data type SQLINTEGER, which was used in previous versions of Db2, is still valid. However, for maximum application portability, using SQLLEN is recommended.

Usage

SQLBindParameter() associates, or binds, parameter markers in an SQL statement to the following objects:

All C type application variables or arrays of C type application variables (storage buffers). For application variables, data is transferred from your application to the database management system when you call SQLExecute() or SQLExecDirect(). This transfer converts data from the C type of the application variable to the SQL type that you specify in the SQLBindParameter() call.
SQL LOB type LOB locators. For LOB data types, you transfer a LOB locator value (not the LOB data itself) to the server when you execute an SQL statement.

SQLBindParameter() also binds application storage to a parameter in a stored procedure CALL statement. In this type of bind, parameters can be input, output, or both input and output parameters.

Call SQLBindParameter() to bind parameter markers to application variables. Parameter markers are question mark characters (?) that you place in an SQL statement. When you execute a statement that contains parameter markers, each of these markers is replaced with the contents of a host variable.

SQLBindParameter() essentially extends the capability of the SQLSetParam() function by providing the following functionality:

Can specify whether a parameter is input, output, or both input and output, which is necessary to handle parameters for stored procedures properly.
Can specify an array of input parameter values when SQLSetStmtAttr() is used in conjunction with SQLBindParameter(). SQLSetParam() can still be used to bind single element application variables to parameter markers that are not part of a stored procedure CALL statement.

Use SQLBindParameter() to bind a parameter marker to one of the following sources:

An application variable.
A LOB value from the database server (by specifying a LOB locator).

Binding a parameter marker to an application variable: You must bind a variable to each parameter marker in an SQL statement before you execute that statement. In SQLBindParameter(), the rgbValue argument and the pcbValue argument are deferred arguments. The storage locations you provide for these arguments must be valid and contain input data values when you execute the bound statement. This requirement means that you must follow one of the following guidelines:

Keep calls to SQLExecDirect() or SQLExecute() in the same procedure scope as calls to SQLBindParameter().
Dynamically allocate storage locations that you use for input or output parameters.
Statically declare storage locations that you use for input or output parameters.
Globally declare storage locations that you use for input or output parameters.

Binding a parameter marker to a LOB locator: When you bind LOB locators to parameter markers the database server supplies the LOB value. Your application transfers only the LOB locator value across the network.

With LOB locators, you can use SQLGetSubString(), SQLGetPosition(), or SQLGetLength(). SQLGetSubString() can return either another locator or the data itself. All locators remain valid until the end of the transaction in which you create them (even when the cursor moves to another row), or until you issue the FREE LOCATOR statement.

Obtaining information about the result set: You can call SQLBindParameter() before SQLPrepare() if you know what columns appear in the result set. Otherwise, if you do not know what columns appear in the result set, you must obtain column attributes after you prepare your query statement.

You reference parameter markers by number, which the ipar argument in SQLBindParameter() represents. Parameter markers are numbered sequentially from left to right, starting at 1.

Specifying the parameter type: The fParamType argument specifies the type of the parameter. All parameters in the SQL statements that do not call procedures are input parameters. Parameters in stored procedure calls can be input, input/output, or output parameters. Even though the Db2 stored procedure argument convention typically implies that all procedure arguments are input/output, the application programmer can still choose to specify the nature of input or output more exactly on the SQLBindParameter() to follow a more rigorous coding style. When you set the fParamType argument, consider the following Db2 ODBC behaviors:

If an application cannot determine the type of a parameter in a procedure call, set the fParamType argument to SQL_PARAM_INPUT; if the data source returns a value for the parameter, Db2 ODBC discards it.
If an application has marked a parameter as SQL_PARAM_INPUT_OUTPUT or SQL_PARAM_OUTPUT and the data source does not return a value, Db2 ODBC sets the buffer that the pcbValue argument specifies to SQL_NULL_DATA.
If an application marks a parameter as SQL_PARAM_OUTPUT, data for the parameter is returned to the application after the CALL statement is processed. If the rgbValue and pcbValue arguments are both null pointers, Db2 ODBC discards the output value. If the data source does not return a value for an output parameter, Db2 ODBC sets the pcbValue buffer to SQL_NULL_DATA.
When the fParamType argument is set to SQL_PARAM_INPUT or SQL_PARAM_INPUT_OUTPUT, the storage locations must be valid and contain input data values when the statement is executed. Because the rgbValue and pcbValue arguments are deferred arguments, you must keep either the SQLExecDirect() or the SQLExecute() call in the same procedure scope as the SQLBindParameter() calls, or the argument values for rgbValue and pcbValue must be dynamically allocated or statically or globally declared.
Similarly, if the fParamType argument is set to SQL_PARAM_OUTPUT or SQL_PARAM_INPUT_OUTPUT, the buffers that the rgbValue and pcbValue arguments specify must remain valid until the CALL statement is executed.

Unbinding parameter markers: All parameters that SQLBindParameter() binds remain bound until you perform one of the following actions:

Call SQLFreeHandle() with the HandleType argument set to SQL_HANDLE_STMT.
Call SQLFreeStmt() with the fOption argument set to SQL_RESET_PARAMS.
Call SQLBindParameter() again for the same parameter ipar number.

After an SQL statement is executed, and the results processed, you might want to reuse the statement handle to execute a different SQL statement. If the parameter marker specifications are different (number of parameters, length, or type), you should call SQLFreeStmt() with SQL_RESET_PARAMS to reset or clear the parameter bindings.

The C buffer data type given by fCType must be compatible with the SQL data type indicated by fSqlType, or an error occurs.

Specifying data-at-execution parameters: An application can pass the value for a parameter either in the rgbValue buffer or with one or more calls to SQLPutData(). In calls to SQLPutData(), these parameters are data-at-execution parameters. The application informs Db2 ODBC of a data-at-execution parameter by placing the SQL_DATA_AT_EXEC value in the pcbValue buffer. It sets the rgbValue input argument to a 32-bit value which is returned on a subsequent SQLParamData() call and can be used to identify the parameter position.

Because the data in the variables referenced by rgbValue and pcbValue is not verified until the statement is executed, data content or format errors are not detected or reported until SQLExecute() orSQLExecDirect() is called.

Allocating buffers: For character and binary C data, the cbValueMax argument specifies the length (in bytes) of the rgbValue buffer if it is a single element; or, if the application calls SQLSetStmtAttr() to specify multiple values for each parameter, the cbValueMax argument specifies the length (in bytes) of each element in the rgbValue array, including the nul-terminator. If the application specifies multiple values, cbValueMax is used to determine the location of values in the rgbValue array. For all other types of C data, the cbValueMax argument is ignored.

You can pass the value for a parameter with either the buffer that the rgbValue argument specifies or one or more calls to SQLPutData(). In calls to SQLPutData(), these parameters are data-at-execution parameters. The application informs Db2 ODBC of a data-at-execution parameter by placing the SQL_DATA_AT_EXEC value in the pcbValue buffer. It sets the rgbValue input argument to a 32-bit value which is returned on a subsequent SQLParamData() call and can be used to identify the parameter position.

If the fSqlType argument is SQL_ROWID, the value for the cbColDef argument must be set to 40, which is the maximum length (in bytes) for a ROWID data type. If the cbColDef argument is not set to 40, you will receive one of the following SQLSTATEs:

SQLSTATE 22001 when the cbColDef argument is less than 40
SQLSTATE HY104 when the cbColDef argument is greater than 40

When SQLBindParameter() is used to bind an application variable to an output parameter for a stored procedure, Db2 ODBC can provide some performance enhancement if the rgbValue buffer is placed consecutively in memory after the pcbValue buffer. For example:

struct {  SQLINTEGER  pcbValue;
          SQLCHAR     rgbValue[MAX_BUFFER];
       } column;

Handling encoding schemes: The Db2 ODBC driver determines one of the following encoding schemes for character and graphic data through the settings of the CURRENTAPPENSCH keyword (which appears in the initialization file) and the fCType argument (which you specify in SQLBindParameter() calls):

The ODBC driver places EBCDIC data into application variables when both of the following conditions are true:
- CURRENTAPPENSCH = EBCDIC is specified in the initialization file, the CCSID that is specified for the CURRENTAPPENSCH keyword is an EBCDIC CCSID, or the CURRENTAPPENSCH keyword is not specified in the initialization file.
- The fCType argument specifies SQL_C_CHAR or SQL_C_DBCHAR in the SQLBindParameter() call.
The ODBC driver places Unicode UCS-2 data into application variables when the fCType argument specifies SQL_C_WCHAR in the SQLBindParameter() call.
The ODBC driver places Unicode UTF-8 data into application variables when both of the following conditions are true:
- CURRENTAPPENSCH = UNICODE is specified in the initialization file, or the CCSID that is specified for CURRENTAPPENSCH is a Unicode CCSID (1200, 1208, 13488 or 17584).
- The fCType argument specifies SQL_C_CHAR in the SQLBindParameter() call.
The ODBC driver places ASCII data into application variables when both of the following conditions are true:
- CURRENTAPPENSCH = ASCII is specified in the initialization file, or the CCSID that is specified for CURRENTAPPENSCH is an ASCII CCSID.
- The fCType argument specifies SQL_C_CHAR or SQL_C_DBCHAR in the SQLBindParameter() call.

Return codes

After you call SQLBindParameter(), it returns one of the following values:

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. `SQLBindParameter()` SQLSTATEs
SQLSTATE	Description	Explanation
07006	Invalid conversion.	The conversion from the data value identified by the fCType argument to the data type that is identified by the fSqlType argument, is not a meaningful conversion. (For example, a conversion from SQL_C_TYPE_DATE to SQL_DOUBLE is not meaningful.)
08S01	Communication link failure.	The communication link between the application and data source fails before the function completes.
58004	Unexpected system failure.	An unrecoverable system error occurs.
HY001	Memory allocation failure.	Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY003	Program type out of range.	The fCType argument is not a valid data type or SQL_C_DEFAULT.
HY004	Invalid SQL data type.	The specified value for the fSqlType argument is not a valid SQL data type.
HY009	Invalid use of a null pointer.	The argument OutputHandlePtr is a null pointer.
HY010	Function sequence error.	The function is called after `SQLExecute()` or `SQLExecDirect()` return SQL_NEED_DATA, but data is not sent for all data-at-execution parameters.
HY013	Unexpected memory handling error.	Db2 ODBC is not able to access the memory that is required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The specified value for the cbValueMax argument is less than 0.
HY093	Invalid parameter number.	The specified value for the ipar argument is less than 1.
HY094	Invalid scale value.	HY094 is returned when the specified value for the fSqlType is SQL_TYPE_TIMESTAMP and the value for the ibScale argument is less than 0 or greater than 12.
HY104	Invalid precision value.	This SQLSTATE is returned because the specified value for the fSqlType argument is either SQL_DECIMAL or SQL_NUMERIC, and the specified value for the cbColDef argument is less than 1. This SQLSTATE is returned for the following reason: The specified value for the fCType argument is SQL_C_TYPE_TIMESTAMP_EXT, the value for the fSqlType argument is either SQL_CHAR or SQL_VARCHAR, and the value for the ibScale argument is less than 0 or greater than 12.
HY105	Invalid parameter type.	The fParamType argument does not specify one of the following values: SQL_PARAM_INPUT SQL_PARAM_OUTPUT SQL_PARAM_INPUT_OUTPUT
HYC00	Driver not capable.	This SQLSTATE is returned for one or more of the following reasons: Db2 ODBC or the data source does not support the conversion that is specified by the combination of the specified value for the fCType argument and the specified value for the fSqlType argument. The specified value for the fSqlType argument is not supported by either Db2 ODBC or the data source.

Restrictions

A new value for the pcbValue argument, SQL_DEFAULT_PARAM, was introduced in ODBC 2.0 to indicate that the procedure should use the default value of a parameter, rather than a value sent from the application. Because Db2 stored procedure arguments do not use default values, specification of SQL_DEFAULT_PARAM for the pcbValue argument results in an error when the CALL statement is executed. This error occurs because the SQL_DEFAULT_PARAM value is considered an invalid length.

ODBC 2.0 also introduced the SQL_LEN_DATA_AT_EXEC(length) macro to be used with the pcbValue argument. The macro specifies the sum total length of all character C data or all binary C data that is sent with the subsequent SQLPutData() calls. Because the Db2 ODBC driver does not need this information, the macro is not needed. To check if the driver needs this information, call SQLGetInfo() with the InfoType argument set to SQL_NEED_LONG_DATA_LEN. The Db2 ODBC driver returns 'N' to indicate that this information is not needed by SQLPutData().

Example

The following example shows an application that binds a variety of data types to a set of parameters.

Figure 1. An application that binds data types to parameters

/* ... */
    SQLCHAR         stmt[] =
    "INSERT INTO PRODUCT VALUES (?, ?, ?, ?, ?)";
    SQLINTEGER      Prod_Num[NUM_PRODS] = {
        100110, 100120, 100210, 100220, 100510, 100520, 200110,
        200120, 200210, 200220, 200510, 200610, 990110, 990120,
        500110, 500210, 300100
    };
    SQLCHAR         Description[NUM_PRODS][257] = {
        "Aquarium-Glass-25 litres", "Aquarium-Glass-50 litres",
        "Aquarium-Acrylic-25 litres", "Aquarium-Acrylic-50 litres",
        "Aquarium-Stand-Small", "Aquarium-Stand-Large",
        "Pump-Basic-25 litre", "Pump-Basic-50 litre",
        "Pump-Deluxe-25 litre", "Pump-Deluxe-50 litre",
        "Pump-Filter-(for Basic Pump)",
        "Pump-Filter-(for Deluxe Pump)",
        "Aquarium-Kit-Small", "Aquarium-Kit-Large",
        "Gravel-Colored", "Fish-Food-Deluxe-Bulk",
        "Plastic-Tubing"
    };
    SQLDOUBLE       UPrice[NUM_PRODS] = {
        110.00, 190.00, 100.00, 150.00, 60.00, 90.00, 30.00,
        45.00, 55.00, 75.00, 4.75, 5.25, 160.00, 240.00,
        2.50, 35.00, 5.50
    };
    SQLCHAR         Units[NUM_PRODS][3] = {
        "  ", "  ", "  ", "  ", "  ", "  ", "  ", "  ", "  ",
        "  ", "  ", "  ", "  ", "  ", "kg", "kg", "m"
    };
    SQLCHAR         Combo[NUM_PRODS][2] = {
        "N", "N", "N", "N", "N", "N", "N", "N", "N",
        "N", "N", "N", "Y", "Y", "N", "N", "N"
    };
    SQLUINTEGER     pirow = 0;
/* ... */

    /* Prepare the statement */
    rc = SQLPrepare(hstmt, stmt, SQL_NTS);
    rc = SQLBindParameter(hstmt, 1, SQL_PARAM_INPUT, SQL_C_SLONG, SQL_INTEGER,
                          0, 0, Prod_Num, 0, NULL);
    rc = SQLBindParameter(hstmt, 2, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_VARCHAR,
                     257, 0, Description, 257, NULL);
    rc = SQLBindParameter(hstmt, 3, SQL_PARAM_INPUT, SQL_C_DOUBLE, SQL_DECIMAL,
                          10, 2, UPrice, 0, NULL);
    rc = SQLBindParameter(hstmt, 4, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                          3, 0, Units, 3, NULL);
    rc = SQLBindParameter(hstmt, 5, SQL_PARAM_INPUT, SQL_C_CHAR, SQL_CHAR,
                          2, 0, Combo, 2, NULL);
    rc = SQLParamOptions(hstmt, NUM_PRODS, &pirow);
    rc = SQLExecute(hstmt);
    printf("Inserted %ld Rows\n", pirow);
/* ... */

Figure 2. An application that binds data types to parameters

SQLBindParameter() - Bind a parameter marker to a buffer or LOB locator

ODBC specifications for SQLBindParameter()