SQLGetConnectAttr--Get current setting of a connection attribute

Purpose

Specification: DB2 CLI 5.0 ODBC 3.0 ISO CLI

SQLGetConnectAttr() returns the current setting of a connection attribute.

Syntax 

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

Function arguments

ǥ 87. SQLGetConnectAttr arguments

Data type Argument Use Description
SQLHDBC ConnectionHandle input Connection handle.
SQLINTEGER Attribute input Attribute to retrieve.
SQLPOINTER ValuePtr output A pointer to memory in which to return the current value of the attribute specified by Attribute.
SQLINTEGER BufferLength input
  • If ValuePtr points to a character string, this argument should be the length of *ValuePtr.
  • If ValuePtr is a pointer, but not to a string, then BufferLength should have the value SQL_IS_POINTER.
  • If the value in *ValuePtr is a Unicode string, the BufferLength argument must be an even number.

SQLINTEGER * StringLengthPtr output A pointer to a buffer in which to return the total number of bytes (excluding the null-termination character) available to return in *ValuePtr.
  • 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 BufferLength minus the length of the null-termination character, the data in *ValuePtr is truncated to BufferLength minus the length of the null-termination character and is null-terminated by DB2 CLI.

Usage

A call to SQLGetConnectAttr() returns in *ValuePtr the value of the connection attribute specified in Attribute. In DB2 Everyplace, that value is a 32-bit value and the BufferLength and StringLengthPtr arguments are not used.

The following connection attributes can be retrieved by SQLGetConnectAttr(). For a description of the attributes, see SQLSetConnectAttr--Set options related to a connection.

Depending on the attribute, an application does not need to establish a connection prior to calling SQLGetConnectAttr().

Return Codes

Diagnostics

ǥ 88. SQLGetConnectAttr SQLSTATEs

SQLSTATE Description Explanation
01000 Warning. Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
01004 Data truncated. The data returned in *ValuePtr was truncated to be BufferLength minus the length of a null termination character. The length of the untruncated string value is returned in *StringLengthPtr. (Function returns SQL_SUCCESS_WITH_INFO.)
08003 Connection is closed. An Attribute value was specified that required an open connection.
HY000 General error. An error occurred for which there was no specific SQLSTATE. 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 on process-level memory limitations.
HY090 Invalid string or buffer length. The value specified for the argument BufferLength was less than 0.
HY092 Option type out of range. The value specified for the argument Attribute was not valid.
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.

Related reference