Connection and statement attributes

The IBM® i Access ODBC specification defines several connection and statement attributes.

This ODBC specification is extended with several IBM i Access customized attributes, that are described in the following 2 tables.

Table 1. Customized connection attributes
Attribute Description
CWB_ATTR_PRESERVE_CURSORS Controls the cursor commit behavior and cursor rollback behavior.

Data type: SQLUINTEGER

Possible values:
  • CWB_CB_DELETE - SQL_CB_DELETE is returned for SQLGetInfo's SQL_CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR options.
  • CWB_CB_PRESERVE - SQL_CB_PRESERVE is returned for SQLGetInfo's SQL _CURSOR_COMMIT_BEHAVIOR and SQL_CURSOR_ROLLBACK_BEHAVIOR options.

Default: CWB_CB_PRESERVE
CWB_ATTR_INFO_USERID Specifies the Client User ID string that is sent to the host database. This attribute is set after connected to a database.

Data type: SQLCHAR

Possible values: Any string with a length of 255 or fewer characters.
Note: This attribute can also be specified using the CLIENTUSERID connection string keyword.
CWB_ATTR_INFO_WRKSTNNAME Specifies the Work Station Name string that is sent to the host database.

Data type: SQLCHAR

Possible values: Any string with a length of 255 or fewer characters.
Note: This attribute can also be specified using the CLIENTWRKSTNNAME connection string keyword.
CWB_ATTR_INFO_APPLNAME Specifies the Application Name string that is sent to the host database.

Data type: SQLCHAR

Possible values: Any string with a length of 255 or fewer characters.

Note: This attribute can also be specified using the CLIENTAPPLNAME connection string keyword.
CWB_ATTR_INFO_ACCTSTR Specifies the Accounting ID string that is sent to the host database.

Data type: SQLCHAR

Possible values: Any string with a length of 255 or fewer characters.

Note: This attribute can also be specified using the CLIENTACCTSTR connection string keyword.
CWB_ATTR_INFO_PROGRAMID Specifies the Program ID string that is sent to the host database.

Data type: SQLCHAR

Possible values: Any string with a length of 255 or fewer characters.

Note: This attribute can also be specified using the CLIENTPROGRAMID connection string keyword.
CWB_ATTR_PACKAGE_LIBRARY Specifies the default package library to be used. This should be set prior to preparing a statement on the connection.

Data type: SQLCHAR

Possible values: Any string with a length of 10 or fewer characters.

Note: This attribute can also be specified using the DFTPKGLIB connection string keyword.
CWB_ATTR_PACKAGE_NAME Specifies the package name to be used. This should be set prior to preparing a statement on the connection.

Data type: SQLCHAR

Possible values: Any string with a length of 10 or fewer characters.

Note: This attribute can also be specified using the PKG connection string keyword.
CWB_ATTR_SERVER_JOB_CCSIDNote 1 Returns the job CCSID for the server job associated with the ODBC connection. By default, SQL statements will be sent to the host in this CCSID.

Data type: SQLUINTEGER
CWB_ATTR_DIVIDE_BY_ZERO Specifies whether or not dividing a value by zero should return an error for data in a particular cell in the result set.

Data type: SQLUINTEGER

Possible values:
  • CWB_DIVIDE_BY_ZERO_ERROR - A cell in a result set that contains a value calculated by dividing by zero will be returned as an error.
  • CWB_DIVIDE_BY_ZERO_NULL - A cell in a result set that contains a value calculated by dividing by zero will be returned as a NULL value. No error will be returned.

Default: CWB_DIVIDE_BY_ZERO_ERROR

Note: This attribute can also be specified using the divide by zero option of the DEBUG connection string keyword.
CWB_ATTR_DATA_COMPRESSION Specifies whether to compress data sent to and from the server. In most cases, data compression improves performance due to less data being transmitted between the driver and the server.

Data type: SQLUINTEGER

Possible values:
  • CWB_COMPRESSION_OFF = compression off
  • CWB_COMPRESSION_ON = compression on

Default: CWB_COMPRESSION_OFF

Note: This attribute can also be specified using the COMPRESSION connection string keyword.
CWB_ATTR_TRIM_CHAR_FIELDSNote 2 Specifies whether or not to trim trailing spaces from data returned from CHAR fields. When CWB_DELETE_BLANKS is specified, CHAR fields will appear like VARCHAR fields as VARCHAR fields are always trimmed of trailing spaces.

Data type: SQLUINTEGER

Possible values:
  • CWB_PRESERVE_BLANKS - don't trim CHAR fields
  • CWB_DELETE_BLANKS - trim CHAR fields

Default: CWB_PRESERVE_BLANKS
CWB_ATTR_JOB_INFONote 1 Returns a character string containing information about the prestart job that the ODBC connection is using.

Data type: SQLCHAR

Possible values: A string with length of 26 characters in the following format:
  • 10 character job name (padded with blanks as necessary),
  • 10 character user (padded with blanks as necessary),
  • 6 character job number
CWB_ATTR_EWLM_CORRELATORNote 2 Specifying this attribute allows you to tie your application with the eWLM support (Enterprise Workload Manager).

Data type: A pointer to a buffer containing the IBM Enterprise Workload Manager (eWLM) correlator.

CWB_ATTR_CONCURRENT_ACCESS_RESOLUTION Specifies how conflicting row locks encountered in the transaction should be handled. This only applies to read-only queries with isolation level CS.

Data type: SQLUINTEGER

Possible values:
  • CWB_CC_USE_SERVER_VALUE - Use server setting
  • CWB_CC_USE_CURRENTLY_COMMITTED - Use Currently Committed Rows
  • CWB_CC_WAIT_FOR_OUTCOME - Wait for Outcome
  • CWB_CC_SKIP_LOCKED_DATA - Skip Locks

Default: CWB_CC_USE_SERVER_VALUE

Note: This attribute can also be specified using the CONCURRENTACCESSRESOLUTION connection string keyword.
CWB_ATTR_XA_TXN_TIMEOUT Specifies the amount of time (in seconds) that a distributed transaction waits before timing out. A value of 0 indicates to wait indefinitely for the transaction to finish.

Data type: SQLUINTEGER

Possible values: 0 – 999999999

Default: 0

Note: This attribute can also be specified using the XATXNTIMEOUT connection string keyword.
CWB_ATTR_XA_LOCK_TIMEOUT Specifies the maximum amount of time (in seconds) that a distributed transaction waits on a lock request before timing out. A value of 0 indicates to use the default system settings.

Data type: SQLUINTEGER

Possible values: 0 – 999999999

Default: 0

Note: This attribute can also be specified using the XALOCKTIMEOUT connection string keyword.
CWB_ATTR_XA_RMID An integer value that specifies the RMID to use for XA transaction work. This can be set at anytime. The RMID that is set must be unique for the process. If this value is set to 0, it indicates that any current XA transaction work has been completed for this connection.

Data type: SQLINTEGER

Default: 0
CWB_ATTR_XA_DLL_NAMENote 1 A character string that identifies the IBM i Access driver to call into for XA calls. This string is only valid if the CWB_ATTR_XA_RMID connection attribute has been set. This string is set after the connection is established.

Data type: SQLCHAR

Default: empty-string
CWB_ATTR_XML_DECLARATION Specifies what type of XML declaration should be included with XML columns returned in result sets.

Data type: SQLUINTEGER

Possible values:
  • CWB_XML_NO_DECLARATION - No declarations or byte order marks (BOMs) are added to the output buffer.
  • CWB_XML_INCLUDE_BYTE_ORDER_MARK -A byte order mark (BOM) in the appropriate endianness is prepended to the output buffer if the target encoding is UTF-16.
  • CWB_XML_INCLUDE_DECLARATION - A minimal XML declaration is generated, containing only the XML version.
  • CWB_XML_BOM_AND_DECLARATION - Sets both CWB_XML_INCLUDE_BYTE_ORDER_MARK and CWB_XML_INCLUDE_DECLARATION.
  • CWB_XML_ENCODING_IN_DECLARATION - An encoding attribute that identifies the target encoding is added to any generated XML declaration. Therefore, this setting only has effect when the setting of 2 is also included when computing the value of this attribute.
  • CWB_XML_FULL_DECLARATION - Sets both CWB_XML_INCLUDE_DECLARATION and CWB_XML_ENCODING_IN_DECLARATION.
  • CWB_XML_BOM_AND_FULL_DECLARATION - Sets CWB_XML_INCLUDE_BYTE_ORDER_MARK, CWB_XML_INCLUDE_DECLARATION, and CWB_XML_ENCODING_IN_DECLARATION.

Default: CWB_XML_BOM_AND_FULL_DECLARATION

Note: This attribute can also be specified using the XMLDECLARATION connection string keyword.
CWB_ATTR_XML_STRIP_WHITESPACE Specifies whether whitespace in serialized XML data should be stripped or preserved by DB2 when the data is implicitly parsed without validation.

Data type: SQLUINTEGER

Possible values:
  • CWB_XML_STRIP_WHITESPACE - Strip whitespace
  • CWB_XML_PRESERVE_WHITESPACE - Preserve whitespace

Default: CWB_XML_STRIP_WHITESPACE

Note: This attribute can also be specified using the XMLCURIMPPARSE connection string keyword.
Note 1: This attribute is only valid with SQLGetConnectAttr.
Note 2: This attribute is only valid with SQLSetConnectAttr.
Table 2. Customized statement attributes
Attribute Description
CWB_ATTR_NUM_RESULT_SETSNote 1 Returns how many result sets are available to be fetched. This is useful when a stored procedure has been called and an application wants to know how many result sets the stored procedure generated.

Data type: SQLUINTEGER
CWB_ATTR_DATA_COMPRESSION Allows compression to be turned on an off at the statement level.

Data type: SQLUINTEGER

Possible values:
  • CWB_COMPRESSION_OFF = compression off,
  • CWB_COMPRESSION_ON = compression on

Default: Inherited from the connection handle, which defaults to CWB_COMPRESSION_OFF.
CWB_ATTR_POS_OF_SYNTAX_ERRORNote 1 Returns the offset into a SQL statement at which a SQL syntax error has occurred. This will be set when SQLExecute or SQLExecDirect returns a SQL_ERROR return code.

Data type: SQLUINTEGER
Note 1: This attribute is only valid with SQLGetStatementAttr.