DB2 Version 10.1 for Linux, UNIX, and Windows
DB2 Version 10.1 for Linux, UNIX, and Windows
Sets attributes that govern aspects of connections.
SQLRETURN SQLSetConnectAttr (
SQLHDBC ConnectionHandle, /* hdbc */
SQLINTEGER Attribute, /* fOption */
SQLPOINTER ValuePtr, /* pvParam */
SQLINTEGER StringLength); /* fStrLen */| Data type | Argument | Use | Description |
|---|---|---|---|
| SQLHDBC | ConnectionHandle | input | Connection handle. |
| SQLINTEGER | Attribute | input | Attribute to set, listed in the connection attributes list. |
| 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 pointer to a null-terminated character string. Note that if the Attribute argument is a driver-specific value, the value in *ValuePtr can be a signed integer. Refer to the connection attributes list for details. |
| 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. For character string data, StringLength should contain the number of bytes
in the string. If Attribute is an ODBC-defined
attribute and ValuePtr is an integer, StringLength is ignored. If Attribute is a CLI attribute, the application indicates the nature of the
attribute by setting the StringLength argument.
StringLength can have the following values:
|
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 CLI. All applications that rely on this behavior, however, should be updated to use SQLSetStmtAttr() instead.
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 might be associated with the statements on that connection in the future.
At any time between allocating and freeing a connection, an application can call SQLSetConnectAttr(). 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. Refer to the connection attributes list for details on when each attribute can be set.
Some connection attributes support substitution of a similar value if the data source does not support the value specified in ValuePtr. In such cases, CLI returns SQL_SUCCESS_WITH_INFO and SQLSTATE 01S02 (Option value changed.). 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.
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().
| SQLSTATE | Description | Explanation |
|---|---|---|
| 01000 | General error. | Informational message. (Function returns SQL_SUCCESS_WITH_INFO.) |
| 01S02 | Option value changed. | 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 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 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 is unable to allocate memory required to support execution or completion of the function. It is likely that process-level memory has been exhausted for the application process. Consult the operating system configuration for information about process-level memory limitations. |
| 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 or SQL_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. (CLI returns this SQLSTATE only for connection and statement
attributes that accept a discrete set of values, such as SQL_ATTR_ACCESS_MODE.
For all other connection and statement attributes, 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 CLI. |
| HYC00 | Driver not capable. | The value specified for the argument Attribute was a valid connection or statement attribute for the version of the CLI driver, but was not supported by the data source. |
None.
/* set AUTOCOMMIT on */
cliRC = SQLSetConnectAttr(hdbc,
SQL_ATTR_AUTOCOMMIT,
(SQLPOINTER)SQL_AUTOCOMMIT_ON,
SQL_NTS);
/* ... */
/* set AUTOCOMMIT OFF */
cliRC = SQLSetConnectAttr(hdbc,
SQL_ATTR_AUTOCOMMIT,
(SQLPOINTER)SQL_AUTOCOMMIT_OFF,
SQL_NTS);