Call Level Interface Guide and Reference

SQLGetConnectAttr - Get Current Attribute Setting

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

Table 90. 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 ValuePtr is not a pointer, then BufferLength should have the value SQL_IS_NOT_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.

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 `ValuePtr` is not a pointer, then `BufferLength` should have the value SQL_IS_NOT_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

For a list of attributes that can be set, see SQLSetConnectAttr - Set Connection Attributes. Note that if Attribute specifies an attribute that returns a string, ValuePtr must be a pointer to a buffer for the string. The maximum length of the string, including the null termination character, will be BufferLength bytes.

Depending on the attribute, an application does not need to establish a connection prior to calling SQLGetConnectAttr(). However, if SQLGetConnectAttr() is called and the specified attribute does not have a default and has not been set by a prior call to SQLSetConnectAttr(), SQLGetConnectAttr() will return SQL_NO_DATA.

If Attribute is SQL_ATTR_ TRACE or SQL_ATTR_ TRACEFILE, ConnectionHandle does not have to be valid, and SQLGetConnectAttr() will not return SQL_ERROR if ConnectionHandle is invalid. These attributes apply to all connections. SQLGetConnectAttr() will return SQL_ERROR if another argument is invalid.

While an application can set statement attributes using SQLSetConnectAttr(), an application cannot use SQLGetConnectAttr() to retrieve statement attribute values; it must call SQLGetStmtAttr() to retrieve the setting of statement attributes.

The SQL_ATTR_AUTO_IPD connection attribute can be returned by a call to SQLGetConnectAttr(), but cannot be set by a call to SQLSetConnectAttr().

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_NO_DATA
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 91. 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 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 was unable to allocate memory required to support execution or completion of the function.
HY010 Function sequence error. 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.
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.

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 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 was unable to allocate memory required to support execution or completion of the function.
HY010	Function sequence error.	`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.
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.

Example

See the README file in the sqllib\samples\cli (or sqllib/samples/cli) subdirectory for a list of appropriate samples.

References

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]