`SQLGetConnectAttr()` - Get current attribute setting

SQLGetConnectAttr() returns the current setting of a connection attribute and also allows you to set these attributes.

ODBC specifications for `SQLGetConnectAttr()`

Table 1. `SQLGetConnectAttr()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
3.0	Yes	Yes

Syntax

SQLRETURN  SQLGetConnectAttr (SQLHDBC           ConnectionHandle,
                              SQLINTEGER        Attribute,
                              SQLPOINTER        ValuePtr,
                              SQLINTEGER        BufferLength,
                              SQLINTEGER        *StringLengthPtr);

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. `SQLGetConnectAttr()` arguments
Data type	Argument	Use	Description
SQLHDBC	ConnectionHandle	input	Specifies the connection handle from which you retrieve the attribute value.
SQLINTEGER	Attribute	input	Specifies the connection attribute to retrieve. Refer to `SQLSetConnectAttr()` for a complete list of attributes.
SQLPOINTER	ValuePtr	input	Specifies the pointer to the memory in which to return the current value of the attribute that the Attribute argument indicates. ValuePtr will be a 32-bit unsigned integer value or point to a nul-terminated character string. If the Attribute argument is a driver-specific value, the value in ValuePtr might be a signed integer.
SQLINTEGER	BufferLength	input	Specifies the size, in bytes, of the buffer to which the ValuePtr argument points. This argument behaves differently according to the following types of attributes: For ODBC-defined attributes: If ValuePtr points to a character string, this argument should be the length of ValuePtr. If ValuePtr points to an integer, BufferLength is ignored. For driver-defined attributes (IBM® extension): If ValuePtr points to a character string, this argument should be the length, in bytes, of ValuePtr or SQL_NTS. If SQL_NTS, the driver assumes that the length of ValuePtr is SQL_MAX_OPTIONS_STRING_LENGTH bytes (excluding the nul-terminator). If ValuePtr points to an integer, BufferLength is ignored.
SQLINTEGER *	StringLengthPtr	output	Specifies a pointer to the buffer in which to return the total number of bytes (excluding the nul-termination character) that the ValuePtr argument requires. The following conditions apply to the StringLengthPtr argument: If ValuePtr is a null pointer, no length is returned. If the attribute value is a character string, and the number of bytes available to return is greater than or equal to the value that is specified for the BufferLength argument, the data in ValuePtr is truncated to that specified value minus the length of a nul-termination character. Db2 ODBC nul-terminates the truncated data. If the Attribute argument does not denote a string, Db2 ODBC ignores the BufferLength argument, and it does not return a value into the buffer to which the StringLengthPtr argument points.

Usage

Use SQLGetConnectAttr() to retrieve the value of a connection attribute that is set on a connection handle.

Although you can use SQLSetConnectAttr() to set attribute values for a statement handle, you cannot use SQLGetConnectAttr() to retrieve current attribute values for a statement handle. To retrieve statement attribute values, call SQLGetStmtAttr().

Return codes

After you call SQLGetConnectAttr(), it returns one of the following values:

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_INVALID_HANDLE
SQL_ERROR

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. `SQLGetConnectAttr()` SQLSTATEs
SQLSTATE	Description	Explanation
01000	Warning.	An informational message. (`SQLGetConnectAttr()` returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
01004	Data truncated.	The data that is returned in the buffer that the ValuePtr argument specifies is truncated. The length to which the data is truncated is equal to the value that is specified in the BufferLength argument, minus the length of a nul-termination character. The StringLengthPtr argument specifies a buffer that receives the size of the non-truncated string. (`SQLGetConnectAttr()` returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
08003	Connection is closed.	The Attribute argument specifies a value that requires an open connection, but the connection handle was not in a connected state.
HY000	General error.	An error occurred for which no specific SQLSTATE exists. The error message that `SQLGetDiagRec()` returns in the buffer that the MessageText argument specifies, describes this error and its cause.
HY001	Memory allocation failure.	Db2 ODBC is not able to allocate memory that is required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The value specified for the BufferLength argument is less than 0.
HY092	Option type out of range.	The specified value for the Attribute argument is not valid for this version of Db2 ODBC.
HYC00	Driver not capable.	The specified value for the Attribute argument is a valid connection or statement attribute for this version of the Db2 ODBC driver, but it is not supported by the data source.

Example

The following example prints the current setting of a connection attribute. SQLGetConnectAttr() retrieves the current value of the SQL_ATTR_AUTOCOMMIT statement attribute.

 SQLINTEGER output_nts,autocommit;
 rc = SQLGetConnectAttr( hdbc, SQL_AUTOCOMMIT,
                       &autocommit, 0, NULL ) ;
 CHECK_HANDLE( SQL_HANDLE_DBC, hdbc, rc ) ;
 printf( "\nAutocommit is: " ) ;
 if ( autocommit == SQL_AUTOCOMMIT_ON )
  printf( "ON\n" ) ;
 else
  printf( "OFF\n" ) ;

SQLGetConnectAttr() - Get current attribute setting

ODBC specifications for SQLGetConnectAttr()