SQLSetStmtOption - Set statement option

SQLSetStmtOption() has been deprecated and replaced with SQLSetStmtAttr(). Although this version of DB2® for i CLI continues to support SQLSetStmtOption(), it is recommended that you begin using SQLSetStmtAttr() in your DB2 for i CLI programs so that they conform to the latest standards.

SQLSetStmtOption() 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 SQLSetConnectAttr(). See SQLSetConnectAttr - Set a connection attribute for additional details.

Start of changeUnicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLSetStmtOptionW(). Refer to Unicode in DB2 for iCLI for more information about Unicode support for DB2 CLI.End of change

Syntax

SQLRETURN SQLSetStmtOption  (SQLHSTMT       hstmt,
                             SQLSMALLINT    fOption,
                             SQLPOINTER     vParam);

Function arguments

Table 1. SQLSetStmtOption arguments
Data type Argument Use Description
SQLHSTMT hstmt Input Statement handle.
SQLSMALLINT fOption Input Option to set. Refer to Table 2 for the list of settable statement options.
SQLPOINTER vParam Input Value associated with fOption. vParam can be a pointer to a 32-bit integer value or a character string.

Usage

The SQLSetStmtOption() provides many of the same attribute functions as SQLSetStmtAttr() before V5R3. However, it has since been deprecated, and support for all new attribute functions has gone into SQLSetStmtAttr(). Users should migrate to the nondeprecated interface.

Statement options for an hstmt remain in effect until they are changed by another call to SQLSetStmtOption() 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 statement options.

The format of information set through vParam depends on the specified fOption. The format of each is noted in Table 2.

Refer to Table 2 for the proper statement options.

Note: Because the SQLSetStmtOption() function has been deprecated, not all the options listed in the table are supported."

Return codes

  • SQL_SUCCESS
  • SQL_ERROR
  • SQL_INVALID_HANDLE

Diagnostics

Table 2. SQLStmtOption SQLSTATEs
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 fOption value, a value that is not valid is specified for the argument vParam.

A fOption that is not valid value is specified.

The argument szSchemaName or szTableName 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.

References

Parent topic: DB2 for i CLI functions