Specification: | DB2 CLI 5.0 | ODBC 3.0 | ISO CLI |
SQLSetConnectAttr() sets attributes that govern aspects of connections.
Syntax
SQLRETURN SQLSetConnectAttr(SQLHDBC ConnectionHandle, SQLINTEGER Attribute, SQLPOINTER ValuePtr, SQLINTEGER StringLength);
Function Arguments
Table 148. SQLSetConnectAttr Arguments
Data Type | Argument | Use | Description |
---|---|---|---|
SQLHDBC | ConnectionHandle | input | Connection handle. |
SQLINTEGER | Attribute | input | Attribute to set, listed in Attribute Values. |
SQLPOINTER | ValuePtr | input | Pointer to the value to be associated with Attribute. Depending on the value of Attribute, *ValuePtr will be a 32-bit unsigned integer value or point to a null-terminated character string. Note that if the Attribute argument is a driver-specific value, the value in *ValuePtr may be a signed integer. |
SQLINTEGER | StringLength | input | If Attribute is an ODBC-defined attribute and ValuePtr
points to a character string or a binary buffer, this argument should be the
length of *ValuePtr. If Attribute is an ODBC-defined
attribute and ValuePtr is an integer, StringLength is
ignored.
If Attribute is a DB2 CLI attribute, the application indicates the nature of the attribute by setting the StringLength argument. StringLength can have the following values:
|
Usage
Setting Statement Attributes using SQLSetConnectAttr() no Longer Supported
The ability to set statement attributes using SQLSetConnectAttr() is no longer supported. To support applications written before version 5, some statement attributes can be set using SQLSetConnectAttr() in this release of DB2 CLI. All applications that rely on this behavior, however, should be updated to use SQLSetStmtAttr() instead. See Setting a Subset of Statement Attributes using SQLSetConnectAttr() for more information.
For version 2 applications that continue to set statement attributes using SQLSetConnectAttr(), if an error is returned when a statement attribute is set on one of multiple active statements, the statement attribute is established as the default for statements later allocated on the connection, but it is undefined whether statement attributes previously set on the same call to SQLSetConnectAttr() remain set after the function is aborted and the error is returned. This is one reason why SQLSetConnectAttr() should not be used to set statement attributes.
If SQLSetConnectAttr() is called to set a statement attribute that sets the header field of a descriptor, the descriptor field is set for the application descriptors currently associated with all statements on the connection. However, the attribute setting does not affect any descriptors that may be associated with the statements on that connection in the future.
Connection Attributes
The currently defined attributes and the version of DB2 CLI in which they were introduced are shown below; it is expected that more will be defined to take advantage of different data sources.
An application can call SQLSetConnectAttr() at any time between the time the connection is allocated or freed. All connection and statement attributes successfully set by the application for the connection persist until SQLFreeHandle() is called on the connection.
Some connection attributes can be set only before a connection has been
made; others can be set only after a connection has been made, while some
cannot be set once a statement is allocated. The following table
indicates when each of the connection attributes can be set.
Table 149. When Connection Attributes can be Set
Attribute | Before connection | After connection | After statements allocated |
---|---|---|---|
SQL_ATTR_ACCESS_MODE | Yes | Yes | Yes a |
SQL_ATTR_ASYNC_ENABLE | Yes | Yes | No b |
SQL_ATTR_AUTO_IPD (read only) | No | Yes | Yes |
SQL_ATTR_AUTOCOMMIT | Yes | Yes | Yes c |
SQL_ATTR_CLISCHEMA | Yes | Yes | Yes |
SQL_ATTR_CLOSE_BEHAVIOR | No | Yes | Yes c |
SQL_ATTR_CONN_CONTEXT | Yes | No | No |
SQL_ATTR_CONNECT_NODE | Yes | No | No |
SQL_ATTR_CONNECTTYPE | Yes | No | No |
SQL_ATTR_CURRENT_SCHEMA | Yes | Yes | Yes |
SQL_ATTR_DB2_SQLERRP (read only) | No | Yes | Yes |
SQL_ATTR_DB2ESTIMATE | No | Yes | Yes |
SQL_ATTR_DB2EXPLAIN | No | Yes | Yes |
SQL_ATTR_ENLIST_IN_DTC | No | Yes | Yes |
SQL_ATTR_INFO_ACCTSTR | No | Yes | Yes |
SQL_ATTR_INFO_APPLNAME | No | Yes | Yes |
SQL_ATTR_INFO_USERID | No | Yes | Yes |
SQL_ATTR_INFO_WRKSTNNAME | No | Yes | Yes |
SQL_ATTR_LOGIN_TIMEOUT | Yes | No | No |
SQL_ATTR_LONGDATA_COMPAT | Yes | Yes | Yes |
SQL_ATTR_MAXCONN | Yes | No | No |
SQL_ATTR_OPTIMIZESQLCOLUMNS | Yes | Yes | Yes |
SQL_ATTR_QUIET_MODE | Yes | Yes | Yes |
SQL_ATTR_SYNC_POINT | Yes | No | No |
SQL_ATTR_TRANSLATE_OPTION | Yes | Yes | Yes |
SQL_ATTR_TXN_ISOLATION | No | Yes c | Yes a |
SQL_ATTR_WCHARTYPE | Yes | Yes c | Yes c |
|
Some connection attributes support substitution of a similar value if the data source does not support the value specified in *ValuePtr. In such cases, DB2 CLI returns SQL_SUCCESS_WITH_INFO and SQLSTATE 01S02 (Option value changed.). For example, if the application attempts to set SQL_ATTR_ASYNC_ENABLE to SQL_ASYNC_ENABLE_ON and the server does not support this then DB2 CLI substitutes the value SQL_ASYNC_ENABLE_OFF instead. To determine the substituted value, an application calls SQLGetConnectAttr().
The format of information set through *ValuePtr depends on the specified Attribute. SQLSetConnectAttr() will accept attribute information in one of two different formats: a null-terminated character string or a 32-bit integer value. The format of each is noted in the attribute's description. Character strings pointed to by the ValuePtr argument of SQLSetConnectAttr() have a length of StringLength bytes.
The StringLength argument is ignored if the length is defined by the attribute, as is the case for all attributes introduced before DB2 CLI Version 5.2.
The following version 2 connection attributes (that were set using
SQLSetConnectOption()) have been renamed for version 5:
Table 150. Renamed Connection Attributes
Version 2 name | Version 5 and later name |
---|---|
SQL_ACCESS_MODE | SQL_ATTR_ACCESS_MODE |
SQL_AUTOCOMMIT | SQL_ATTR_AUTOCOMMIT |
SQL_CONNECTTYPE | SQL_ATTR_CONNECTTYPE |
SQL_CURRENT_SCHEMA | SQL_ATTR_CURRENT_SCHEMA |
SQL_DB2ESTIMATE | SQL_ATTR_DB2ESTIMATE |
SQL_DB2EXPLAIN | SQL_ATTR_DB2EXPLAIN |
SQL_LOGIN_TIMEOUT | SQL_ATTR_LOGIN_TIMEOUT |
SQL_LONGDATA_COMPAT | SQL_ATTR_LONGDATA_COMPAT |
SQL_MAXCONN | SQL_ATTR_MAXCONN |
SQL_QUIET_MODE | SQL_ATTR_QUIET_MODE |
SQL_SCHEMA | SQL_ATTR_SCHEMA |
SQL_SYNC_POINT | SQL_ATTR_SYNC_POINT |
SQL_TXN_ISOLATION | SQL_ATTR_TXN_ISOLATION |
SQL_WCHARTYPE | SQL_ATTR_WCHARTYPE |
DB2 CLI does not ensure that requests to the database are read-only. If an update request is issued, DB2 CLI will process it using the transaction isolation level it has selected as a result of the SQL_MODE_READ_ONLY setting.
SQL_MODE_READ_WRITE is the default.
There must not be any outstanding transactions on this connection.
A 32-bit integer value that specifies whether a function called with a statement on the specified connection is executed asynchronously:
Setting SQL_ASYNC_ENABLE_ON enables asynchronous execution for all future statement handles allocated on this connection. This also enables asynchronous execution for existing statement handles associated with this connection. An error is returned if asynchronous execution is turned on while there is an active statement on the connection.
This attribute can be set whether SQLGetInfo(), called with the InfoType SQL_ASYNC_MODE, returns SQL_AM_CONNECTION or SQL_AM_STATEMENT.
Once a function has been called asynchronously, only the original function, SQLAllocHandle(), SQLCancel(), SQLGetDiagField(), or SQLGetDiagRec() can be called on the statement or the connection associated with StatementHandle, until the original function returns a code other than SQL_STILL_EXECUTING. Any other function called on StatementHandle or the connection associated with StatementHandle returns SQL_ERROR with an SQLSTATE of HY010 (Function sequence error). Functions can be called on other statements.
In general, applications should execute functions asynchronously only on single-threaded operating systems. On multi-threaded operating systems, applications should execute functions on separate threads, rather than executing them asynchronously on the same thread. Applications that only operate on multi-threaded operating systems do not need to support asynchronous execution. For more information, see Writing Multi-Threaded Applications and Asynchronous Execution of CLI.
The following functions can be executed asynchronously:
SQLColAttribute() SQLGetTypeInfo() SQLColumnPrivileges() SQLMoreResults() SQLColumns() SQLNumParams() SQLCopyDesc() SQLNumResultCols() SQLDescribeCol() SQLParamData() SQLDescribeParam() SQLPrepare() SQLExecDirect() SQLPrimaryKeys() SQLExecute() SQLProcedureColumns() SQLFetch() SQLProcedures() SQLFetchScroll() SQLPutData() SQLForeignKeys() SQLSetPos() SQLGetData() SQLSpecialColumns() SQLGetDescField() 1* SQLStatistics() SQLGetDescRec() 1* SQLTablePrivileges() SQLGetDiagField() SQLTables() SQLGetDiagRec() 1* These functions can be called asynchronously only if the descriptor is an implementation descriptor, not an application descriptor.
A read-only 32-bit integer value that specifies whether automatic population of the IPD after a call to SQLPrepare() is supported:
If SQL_TRUE is returned for the SQL_ATTR_AUTO_IPD connection attribute, the statement attribute SQL_ATTR_ENABLE_AUTO_IPD can be set to turn automatic population of the IPD on or off. If SQL_ATTR_AUTO_IPD is SQL_FALSE, SQL_ATTR_ENABLE_AUTO_IPD cannot be set to SQL_TRUE.
The default value of SQL_ATTR_ENABLE_AUTO_IPD is equal to the value of SQL_ATTR_AUTO_IPD.
This connection attribute can be returned by SQLGetConnectAttr(), but cannot be set by SQLSetConnectAttr().
SQL_AUTOCOMMIT_ON is the default.
Note: | If this is a coordinated distributed unit of work connection, then the default is SQL_AUTOCOMMIT_OFF |
Since in many DB2 environments, the execution of the SQL statements and the commit may be flowed separately to the database server, autocommit can be expensive. It is recommended that the application developer take this into consideration when selecting the auto-commit mode.
Note: | Changing from manual commit to auto-commit mode will commit any open transaction on the connection. |
DB2 CLI Version 1 applications assume the default is manual commit mode. Refer to Incompatibilities.
A null-terminated character string containing the name of the DB2 ODBC catalog view stored on the host DBMS to use.
The DB2 ODBC catalog is designed to improve the performance of schema calls for lists of tables in ODBC applications that connect to host DBMSs through DB2 Connect.
The DB2 ODBC catalog, created and maintained on the host DBMS, contains rows representing objects defined in the real DB2 catalog, but these rows include only the columns necessary to support ODBC operations. The tables in the DB2 ODBC catalog are pre-joined and specifically indexed to support fast catalog access for ODBC applications.
System administrators can create multiple DB2 ODBC catalog views, each containing only the rows that are needed by a particular user group. Each end user can then select the DB2 ODBC catalog view they wish to use (by setting this attribute).
While this attribute has some similar effects as the SYSSCHEMA keyword, SQL_ATTR_CLISCHEMA should be used instead (where applicable). SQL_ATTR_CLISCHEMA improves data access efficiency: The user-defined tables used with SYSSCHEMA were mirror images of the DB2 catalog tables, and the ODBC driver still had to join rows from multiple tables to produce the information required by the ODBC user. Using SQL_ATTR_CLISCHEMA also results in less contention on the catalog tables.
There is also a corresponding DB2 CLI/ODBC Driver configuration keyword; CLISCHEMA
A 32-bit integer that specifies whether the DB2 server should attempt to release read locks acquired during a cursor's operation when the cursor is closed. It can be set to either:
For cursors opened with isolation UR or CS, read locks are not held after a cursor moves off a row. For cursors opened with isolation RS or RR, SQL_ATTR_CLOSE_BEHAVIOR modifies some of those isolation levels, and an RR cursor may experience nonrepeatable reads or phantom reads.
If a cursor that is originally RR or RS is reopened after being closed with SQL_ATTR_CLOSE_BEHAVIOR then new read locks will be acquired.
For more information see SQLCloseCursor - Close Cursor and Discard Pending Results.
Indicates which context the connection should use. An SQLPOINTER to either:
This attribute can only be used when the application is using the DB2 context APIs to manage multi-threaded applications. By default, DB2 CLI manages contexts by allocating one context per connection handle, and ensuring that any executing thread is attached to the correct context.
For more information about when an application may have to manage contexts, refer to Writing Multi-Threaded Applications.
For more information about contexts, refer to the sqleBeginCtx() API in the Administrative API Reference.
If this variable is not set, the target logical node defaults to the logical node which is defined with port 0 on the machine.
There is also a corresponding DB2 CLI/ODBC Driver configuration keyword; CONNECTTYPE.
A READ ONLY 32-bit integer value that indicates whether or not the connection is still active. DB2 CLI will return one of the following values:
This attribute is used mainly by the Microsoft ODBC Driver Manager 3.5x before pooling the connection.
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
A 32-bit integer value corresponding to the number of seconds to wait for any request on the connection to complete before returning to the application.
DB2 CLI always behaves as if ValuePtr was set to 0 (the default); there is no time out.
The current setting of the SQL_ATTR_SYNC_POINT option is ignored.
This is the default.
Note: | This connection type results in the default for SQL_ATTR_AUTOCOMMIT connection option to be SQL_AUTOCOMMIT_OFF. |
This option must be set before making a connect request; otherwise, the SQLSetConnectOption() call will be rejected.
All the connections within an application must have the same SQL_ATTR_CONNECTTYPE and SQL_ATTR_SYNC_POINT values. The first connection determines the acceptable attributes for the subsequent connections. We recommend that the application set the SQL_ATTR_CONNECTTYPE attribute at the environment level rather than on a per connection basis. ODBC applications written to take advantage of coordinated DB2 transactions must set these attributes at the connection level for each connection as SQLSetEnvAttr() is not supported in ODBC.
The default connect type can also be set using the CONNECTTYPE DB2 CLI/ODBC configuration keyword. See Configuring db2cli.ini for more information.
Note: | This is an IBM defined extension. |
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
A null-terminated character string containing the name of the catalog to be used by the data source.
To reset this option, specify this option with a zero length or a null pointer for the ValuePtr argument.
This option is useful when the application developer has coded a generic call to SQLColumns() that does not restrict the result set by schema name, but needs to constrain the result set at isolated places in the code.
This option can be set at any time and will be effective on the next SQLColumns() call where the szSchemaName pointer is null.
Note: | This is an IBM defined extension. |
Begins with a three-letter identifier indicating the product, followed by five digits indicating the version, release, and modification level of the product. For example, SQL05000 means DB2 Universal Database versions for Version 5 Release 0 Modification level 0.
If SQLCODE indicates an error condition, then this field identifies the module that returned the error.
This field is also used when a successful connection is completed.
See the SQL Reference for more information on the sqlca and this particular field.
This is the default.
The graphical window will display optimizer estimates, along with push buttons to allow the user to choose whether they wish to continue with subsequent execution of this query or to cancel it.
The recommended value for this option is 60000.
This option is used in conjunction with SQL_ATTR_QUIET_MODE and is applicable only to applications with graphical user interfaces. The application can implement this feature directly without using this option by calling SQLGetSQLCA() after an SQLPrepare() for a query and then displaying the appropriate information, thus allowing a more integrated overall interface.
The new SQL_ATTR_DB2ESTIMATE setting is effective on the next statement preparation for this connection.
Note: | This is an IBM defined extension. |
Before the explain information can be generated, the explain tables must be created. See the SQL Reference for additional information.
This statement is not under transaction control and is not affected by a ROLLBACK. The new SQL_ATTR_DB2EXPLAIN setting is effective on the next statement preparation for this connection.
The current authorization ID must have INSERT privilege for the Explain tables.
This value can also be set using the DB2EXPLAIN DB2 CLI/ODBC configuration keyword. See Configuring db2cli.ini for more information.
Note: | This is an IBM defined extension. |
An SQLPOINTER which can be either:
The application is asking the DB2 CLI/ODBC driver to change the state of the connection from non-distributed transaction state to distributed state. The connection will be enlisted with the Distributed Transaction Coordinator (DTC).
The application is asking the DB2 CLI/ODBC driver to change the state of the connection from distributed transaction state to a non-distributed transaction state.
This attribute is only used in a Microsoft Transaction Server (MTS) environment to enlist or un-enlist a connection with MTS.
Each time this attribute is used with a non-null transaction pointer, the previous transaction is assumed to be ended and a new transaction is initiated. The application must call the ITransaction member function Endtransaction before calling this API with a non-null pointer. Otherwise the previous transaction will be aborted. The application can enlist mutiple connections with the same transaction pointer.
Note: | This connection attribute is specified by MTS automatically for each transaction and is not coded by the user application. |
A null-terminated character string used to identify the client accounting string sent to the host database server when using DB2 Connect. Please note:
Note: | This is an IBM defined extension. |
A null-terminated character string used to identify the client application name sent to the host database server when using DB2 Connect. Please note:
Note: | This is an IBM defined extension. |
A null-terminated character string used to identify the client user ID sent to the host database server when using DB2 Connect. Please note:
Note: | This is an IBM defined extension. |
A null-terminated character string used to identify the client workstation name sent to the host database server when using DB2 Connect. Please note:
Note: | This is an IBM defined extension. |
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
A 32-bit integer value corresponding to the number of seconds to wait for a login request to complete before returning to the application. The only permitted value for the ValuePtr argument is 0, which means the connection attempt will wait until either a connection is established or the underlying communication layer times out.
Note: | This is an IBM defined extension. |
This can be used as a governor for the maximum number of connections on a per application basis.
On OS/2, Windows 95, and Windows NT, if the NetBIOS protocol is in use, this value corresponds to the number of connections (NetBIOS sessions) that will be concurrently set up by the application. The range of values for OS/2 NetBIOS is 1 to 254. Specifying 0 (the default) will result in 5 reserved connections. Reserved NetBIOS sessions cannot be used by other applications. The number of connections specified by this parameter will be applied to any adaptor that the DB2 NetBIOS protocol uses to connect to the remote server (adapter number is specified in the node directory for a NetBIOS node).
The value that is in effect when the first connection is established is the value that will be used. Once the first connection has been established, attempts to change this value will be rejected. We recommended that the application set SQL_ATTR_MAXCONN at the environment level rather then on a connection basis. ODBC applications must set this attribute at the connection level since SQLSetEnvAttr() is not supported in ODBC.
The maximum concurrent connections can also be set using the MAXCONN DB2 CLI/ODBC configuration keyword. See Configuring db2cli.ini for more information.
Note: | This is an IBM defined extension. |
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
An SQLUINTEGER value that determines how the string arguments of catalog functions are treated.
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
A 32-bit option specifying how the Driver Manager uses the ODBC cursor library.
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
A 32-bit integer value specifying the network packet size in bytes.
If the application has never made a call to SQLSetConnectOption() with this option, then DB2 CLI would return a null parent window handle on SQLGetConnectOption() for this option and use a null parent window handle to display dialogue boxes. For example, if the end user has asked for (via an entry in the DB2 CLI initialization file) optimizer information to be displayed, DB2 CLI would display the dialogue box containing this information using a null window handle. (For some platforms, this means the dialogue box would be centered in the middle of the screen.)
If ValuePtr is a null pointer, then DB2 CLI does not display any dialogue boxes. In the above example where the end user has asked for the optimizer estimates to be displayed, DB2 CLI would not display these estimates because the application explicitly wants to suppress all such dialogue boxes.
If ValuePtr is not a null pointer, then it should be the parent window handle of the application. DB2 CLI uses this handle to display dialogue boxes. (For some platforms, this means the dialogue box would be centered with respect to the active window of the application.)
Note: | This connection option cannot be used to suppress the SQLDriverConnect() dialogue box (which can be suppressed by setting the fDriverCompletion argument to SQL_DRIVER_NOPROMPT). |
Refer to the SQL Reference for more information on distributed unit of work (transactions).
All the connections within an application must have the same SQL_ATTR_CONNECTTYPE and SQL_SYNCPOINT values. The first connection determines the acceptable attributes for the subsequent connections. We recommend that the application set the SQL_ATTR_CONNECTTYPE attribute at the environment level rather than on a per connection basis. ODBC applications written to take advantage of coordinated DB2 transactions must set these attributes at the connection level as SQLSetEnvAttr() is not supported in ODBC.
The type of coordinated transaction can also be set using the SYNCPOINT DB2 CLI/ODBC configuration keyword. See Configuring db2cli.ini for more information.
Note: | This is an IBM extension. In embedded SQL, there is an additional sync point setting called SYNCPOINT NONE. This is more restrictive than the SQL_CONCURRENT_TRANS setting of the SQL_ATTR_CONNECTTYPE option because SYNCPOINT NONE does not allow for multiple connections to the same database. As a result, it is not necessary for DB2 CLI to support SYNCPOINT NONE. |
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
A 32-bit integer value telling DB2 CLI whether to perform tracing.
Instead of using the attribute, the DB2 CLI trace facility can be set using the TRACE DB2 CLI/ODBC configuration keyword. See Configuring db2cli.ini for more information.
This connection attribute is defined by ODBC, but is not supported by DB2 CLI. Any attempt to set or get this attribute will result in an SQLSTATE of HYC00 (Driver not capable).
A null-terminated character string containing the name of the trace file.
Instead of using this attribute, the DB2 CLI trace file name is set using the TRACEFILENAME DB2 CLI/ODBC configuration keyword. See Configuring db2cli.ini for more information.
This connection attribute is defined by ODBC, but is only supported by DB2 CLI on Windows 3.1. Any attempt to set or get this attribute on other platforms will result in an SQLSTATE of HYC00 (Driver not capable).
Indicate the directory where the DB2 Client Application Enabler for Windows or the Software Developers Kit for Windows has been installed. DB2TRANS.DLL is the DLL that contains codepage mapping tables.
This option is used on 16-bit versions of Windows when connecting to DB2 for OS/2 Version 1, or when using a version of DDCS for OS/2 prior to Version 2.3 in conjunction with the TRANSLATEOPTION, to provide proper mapping of NLS SBCS characters (such as the umlaut character in German) to the corresponding characters in the Windows codepage 1004.
Note: | This option is useful when a Windows application connects to a downlevel server that does not support unequal codepage conversion (such as DB2 Version 1). |
This connection attribute is defined by ODBC, but is only supported by DB2 CLI on Windows 3.1. Any attempt to set or get this attribute on other platforms will result in an SQLSTATE of HYC00 (Driver not capable).
Defines the codepage number of the database in DB2 Version 1 (it can be obtained by querying the database configuration parameters). Specifying TRANSLATEDLL and TRANSLATEOPTION enables the translation of characters from codepage number database codepage number to the Windows 1004 codepage.
There are two supported values for database codepage number: 437 and 850. If you specify any other values, a warning is returned on the connect request indicating that translation is not possible.
Note: | This option is useful when a Windows application connects to a downlevel server that does not support unequal codepage conversion (such as DB2 Version 1). |
This is the default.
In IBM terminology,
For a detailed explanation of Isolation Levels, refer to the SQL Reference.
This option cannot be specified while there is an open cursor on any hstmt, or an outstanding transaction for this connection; otherwise, SQL_ERROR is returned on the function call (SQLSTATE S1011).
This attribute (or corresponding keyword) is only applicable if the default isolation level is used. If the application has specifically set the isolation level then this attribute will have no effect.
Note: | There is an IBM extension that permits the setting of transaction isolation levels on a per statement handle basis. See the SQL_STMTTXN_ISOLATION option in the function description for SQLSetStmtOption(). |
This is the default.
For additional information on the use of multi-byte application variables, refer to the Application Development Guide
Note: | This is an IBM defined extension. |
Return Codes
Diagnostics
DB2 CLI can return SQL_SUCCESS_WITH_INFO to provide information about the result of setting an option.
When Attribute is a statement attribute,
SQLSetConnectAttr() can return any SQLSTATEs returned by SQLSetStmtAttr().
Table 151. SQLSetConnectAttr SQLSTATEs
SQLSTATE | Description | Explanation |
---|---|---|
01000 | General error. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
01S02 | Option value changed. | DB2 CLI did not support the value specified in *ValuePtr and substituted a similar value. (Function returns SQL_SUCCESS_WITH_INFO.) |
08002 | Connection in use. | The argument Attribute was SQL_ATTR_ODBC_CURSORS and DB2 CLI was already connected to the data source. |
08003 | Connection is closed. | An Attribute value was specified that required an open connection, but the ConnectionHandle was not in a connected state. |
08S01 | Communication link failure. | The communication link between DB2 CLI and the data source to which it was connected failed before the function completed processing. |
24000 | Invalid cursor state. | The argument Attribute was SQL_ATTR_CURRENT_QUALIFIER and a result set was pending. |
HY000 | General error. | An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by SQLGetDiagRec() in the *MessageText buffer describes the error and its cause. |
HY001 | Memory allocation failure. | DB2 CLI was unable to allocate memory required to support execution or completion of the function. |
HY009 | Invalid argument value. | A null pointer was passed for ValuePtr and the value in *ValuePtr was a string value. |
HY010 | Function sequence error. | An asynchronously executing function was called for a
StatementHandle associated with the ConnectionHandle and was
still executing when SQLSetConnectAttr() was called.
SQLExecute() or SQLExecDirect()was called for a StatementHandle associated with the ConnectionHandle and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns. SQLBrowseConnect() was called for the ConnectionHandle and returned SQL_NEED_DATA. This function was called before SQLBrowseConnect() returned SQL_SUCCESS_WITH_INFO orSQL_SUCCESS. |
HY011 | Operation invalid at this time. | The argument Attribute was SQL_ATTR_TXN_ISOLATION and a transaction was open. |
HY024 | Invalid attribute value. | Given the specified Attribute value, an invalid value was
specified in *ValuePtr. (DB2 CLI returns this SQLSTATE only
for connection and statement attributes that accept a discrete set of values,
such as SQL_ATTR_ACCESS_MODE or SQL_ATTR_ASYNC_ENABLE. For all other
connection and statement attributes, DB2 CLI must verify the value specified
in ValuePtr.)
The Attribute argument was SQL_ATTR_TRACEFILE or SQL_ATTR_TRANSLATE_LIB, and *ValuePtr was an empty string. |
HY090 | Invalid string or buffer length. | The StringLength argument was less than 0, but was not SQL_NTS. |
HY092 | Option type out of range. | The value specified for the argument Attribute was not valid for this version of DB2 CLI. |
HYC00 | Driver not capable. | The value specified for the argument Attribute was a valid connection or statement attribute for the version of the DB2 CLI driver, but was not supported by the data source. |
Restrictions
None.
Example
See the CLI sample samputil.c .
References