SQLParamOptions() - Specify an input array for a parameter

SQLParamOptions() is a deprecated function and is replaced by SQLSetStmtAttr().

ODBC specifications for SQLParamOptions()

Table 1. SQLParamOptions() specifications
ODBC specification level In X/Open CLI CAE specification? In ISO CLI specification?
1.0 (Deprecated) No No

Syntax

SQLRETURN   SQLParamOptions  (SQLHSTMT          hstmt,
                              SQLUINTEGER       crow,
                              SQLUINTEGER  FAR  *pirow);

Function arguments

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

Table 2. SQLParamOptions() arguments
Data type Argument Use Description
SQLHSTMT hstmt input Specifies a statement handle.
SQLUINTEGER crow input Specifies the number of values for each parameter. If this value is greater than 1, then the rgbValue argument in SQLBindParameter() points to an array of parameter values, and the pcbValue argument points to an array of lengths.
SQLUINTEGER * pirow output (deferred) Points to a buffer for the current parameter array index. As each set of parameter values is processed, this argument is set to the array index of that set. If a statement fails, this value can be used to determine how many statements were successfully processed. No value is returned if the pirow argument specifies a null pointer.

Usage

Use SQLParamOptions() to prepare a statement, and to execute that statement repeatedly for an array of parameter markers.

As a statement executes, the buffer to which the pirow argument points is set to the index of the current array of parameter values. If an error occurs during execution for a particular element in the array, execution halts and SQLExecute(), SQLExecDirect(), or SQLParamData() returns SQL_ERROR.

The output argument pirow points to a buffer that returns how many sets of parameters were successfully processed. If the statement that is processed is a query, pirow points to a buffer that returns the array index that is associated with the current result set, which returned by SQLMoreResults(). This value increments each time SQLMoreResults() is called.

Use the value in the buffer to which the pirow argument points for the following cases:
  • When SQLParamData() returns SQL_NEED_DATA, use the value to determine which set of parameters need data.
  • When SQLExecute() or SQLExecDirect() returns an error, use the value to determine which element in the parameter value array failed.
  • When SQLExecute(), SQLExecDirect(), SQLParamData(), or SQLPutData() succeeds, the value is set to the value that the crow argument specifies to indicate that all elements of the array have been processed successfully.
If the statement to which SQLParamOptions() refers is a MERGE statement:
  • Use SQLParamOptions() to set the number of rows in the source data to be merged into the target table or view.
  • If a MERGE statement contains an UPDATE or INSERT clause with parameter markers, SQLParamOptions() has no effect on the parameter markers in the UPDATE or INSERT clause.
  • The buffer to which pirow points contains the number of rows that are affected by the MERGE.

Return codes

After you call SQLParamOptions(), 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. SQLParamOptions() SQLSTATEs
SQLSTATE Description Explanation
08S01 Communication link failure. The communication link between the application and data source fails before the function completes.
HY001 Memory allocation failure. Db2 ODBC is not able to allocate the required memory to support the execution or the completion of the function.
HY010 Function sequence error. The function is called during a data-at-execute operation. (That is, the function is called during a procedure that uses the SQLParamData() or SQLPutData() functions.)
HY107 Row value out of range. The value in the crow argument is less than 1.

Example

In ODBC 3.0, the call to SQLParamOptions() is replaced with two calls to SQLSetStmtAttr():

SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMSET_SIZE, crow, 0);
SQLSetStmtAttr(hstmt, SQL_ATTR_PARAMS_PROCESSED_PTR, piRow, 0);