SQLSetStmtAttr - Set a statement attribute
SQLSetStmtAttr()
sets
an attribute of a specific statement handle. To set an option for
all statement handles associated with a connection handle, the application
can call SQLSetConnectOption()
.
SQLSetStmtAttrW()
. Refer to Unicode in Db2 for i CLI for more information about Unicode
support for DB2® CLI.Syntax
SQLRETURN SQLSetStmtAttr (SQLHSTMT hstmt,
SQLINTEGER fAttr,
SQLPOINTER vParam,
SQLINTEGER sLen);
Function arguments
Data type | Argument | Use | Description |
---|---|---|---|
SQLHSTMT | hstmt | Input | Statement handle. |
SQLINTEGER | fAttr | Input | Attribute to set. Refer to Table 2 for the list of settable statement attributes. |
SQLPOINTER | vParam | Input | Value associated with fAttr. vParam can be a 32-bit integer value or a character string. |
SQLINTEGER | sLen | Input | Length of data if data is a character string; otherwise, unused. |
Usage
Statement options for an hstmt remain
in effect until they are changed by another call to SQLSetStmtAttr()
or
the hstmt is dropped by calling SQLFreeStmt()
with
the SQL_DROP option. Calling SQLFreeStmt()
with the
SQL_CLOSE, SQL_UNBIND, or SQL_RESET_PARAMS options does not reset
the statement options.
The format of information set through vParam depends on the specified fOption. The format of each is noted in Table 2.
fAttr | Contents |
---|---|
SQL_ATTR_APP_PARAM_DESC | VParam must be a descriptor
handle. The specified descriptor serves as the application parameter
descriptor for later calls to SQLExecute() and SQLExecDirect() on
the statement handle. |
SQL_ATTR_APP_ROW_DESC | VParam must be a descriptor
handle. The specified descriptor serves as the application row descriptor
for later calls to SQLFetch() on the statement handle. |
SQL_ATTR_BIND_TYPE | This specifies whether row-wise or column-wise
binding is used.
|
SQL_ATTR_CURSOR_HOLD | A 32-bit integer value that specifies
if cursors opened for this statement handle should be held.
|
SQL_ATTR_CURSOR_SCROLLABLE | A 32-bit integer value that specifies
if cursors opened for this statement handle should be scrollable.
|
SQL_ATTR_CURSOR_SENSITIVITY | A 32-bit integer value that specifies whether cursors opened for this
statement handle make visible the changes made to the result set by another cursor. See DECLARE CURSOR for a more
precise definition of the following options:
|
SQL_ATTR_CURSOR_TYPE | A 32-bit integer value that specifies
the behavior of cursors opened for this statement handle.
|
SQL_ATTR_EXTENDED_COL_INFO | A 32-bit integer value that specifies
if cursors opened for this statement handle should provide extended
column information.
|
SQL_ATTR_FOR_FETCH_ONLY | A 32-bit integer value that specifies
whether cursors opened for this statement handle should be read only:
|
SQL_ATTR_FULL_OPEN | A 32-bit integer value that specifies
if cursors opened for this statement handle should be full open operations.
|
SQL_ATTR_NUMBER_RESULTSET_ROWS_PTR | A 32-bit integer * value the points to a buffer which contains the total number of rows available from the result set. This attribute will only return a valid result if the cursor sensitivity is insensitive and the cursor type is static. Without these settings, the returned result will be zero. This value is set after a successful call to SQLExecute() or SQLExecDirect(). |
SQL_ATTR_PARAM_BIND_TYPE | A 32-bit integer value:
|
SQL_ATTR_PARAM_STATUS_PTR | A 32-bit integer * value that points to an array
of values containing status information for each row of parameter
values. The status values are set after a call to SQLExecDirect() or SQLExecute() .
This field is used only if SQL_ATTR_PARAMSET_SIZE is greater than
1. The following status values can be returned.
|
SQL_ATTR_PARAMS_PROCESSED_PTR | A 32-bit integer * value that points to the
current row number. As each row of parameters is processed this is
set to the number of that row. If the call to SQLExecDirect() or SQLExecute()
that fills in the SQLINTEGER buffer pointed to by this attribute does
not return SQL_SUCCESS or SQL_SUCCESS_WITH_INFO, the contents of the
buffer are undefined. This statement attribute can be set to a null pointer, in which case DB2 CLI does not return the row number. |
SQL_ATTR_PARAMSET_SIZE | A 32-bit integer value that specifies the number
of values to be associated with each parameter marker. If this is
greater that 1, the rgbValue argument in SQLBindParameter() points
to an array of parameter values, and pcbValue points to an
array of lengths. This is an alternative to setting a value size through
the SQLParamOptions() API. |
SQL_ATTR_ROW_BIND_TYPE | A 32-bit integer value:
|
SQL_ATTR_ROW_STATUS_PTR | A 16-bit SMALLINT * value that points to an
array of status values at SQLFetchScroll() . The number
of elements must equal the number of rows in the row set (as defined
by the SQL_ROWSET_SIZE attribute). A status value SQL_ROW_SUCCESS
for each row fetched is returned.If the number of rows fetched is less than the number of elements in the status array (that is, less than the row set size), the remaining status elements are set to SQL_ROW_NOROW. The number of rows fetched is returned in the output pointer. This can be set by the SQLSetStmtAttr attribute SQL_ATTR_ROWS_FETCHED_PTR. Db2 for i CLI cannot detect whether a row has been updated or deleted since the start of the fetch. Therefore, the following ODBC defined status values are not reported:
|
SQL_ATTR_ROWS_FETCHED_PTR | A 32-bit integer * value that points to a buffer
that contains the number of rows actually fetched by SQLFetchScroll() .
If an error occurs during processing, the pointer points to the ordinal
position of the row (in the row set) that precedes the row where the
error occurred. If an error occurs retrieving the first row, the pointer
points to the value 0. |
SQL_ATTR_ROWSET_SIZE | A 32-bit integer value that specifies
the number of rows in the row set. This is the number of rows returned
by each call to SQLExtendedFetch() . The maximum value
is 32767. The default value is 1. |
Return codes
- SQL_SUCCESS
- SQL_ERROR
- SQL_INVALID_HANDLE
Diagnostics
SQLSTATE | Description | Explanation |
---|---|---|
40003 * | Statement completion unknown | The communication link between the CLI and the data source fails before the function completes processing. |
HY000 | General error | An error occurred for which there is no specific SQLSTATE and for which no implementation defined SQLSTATE is defined. The error message returned by SQLError in the argument szErrorMsg describes the error and its cause. |
HY001 | Memory allocation failure | The driver is unable to allocate memory required to support the processing or completion of the function. |
HY009 | Argument value that is not valid | Given the specified fAttr value,
a value that is not valid is specified for the argument vParam.
An fAttr value that is not valid is specified. The argument vParam is a null pointer. |
HY010 | Function sequence error | The function is called out of sequence. |
HYC00 | Driver not capable | The driver or the data sources does not support the specified option. |