SQLGetStmtAttr--Get current setting of a statement attribute

Purpose

Specification:

DB2 CLI 5.0

ODBC 3.0

ISO CLI

SQLGetStmtAttr() returns the current setting of a statement attribute.

Syntax

SQLRETURN   SQLGetStmtAttr       (
                SQLHSTMT             StatementHandle,
                SQLINTEGER           Attribute,
                SQLPOINTER           ValuePtr,
                SQLINTEGER           BufferLength,
                SQLINTEGER          *StringLengthPtr);

Function arguments

ǥ 70. SQLGetStmtAttr arguments

Data type	Argument	Use	Description
SQLHSTMT	`StatementHandle`	input	Statement handle.
SQLINTEGER	`Attribute`	input	Attribute to retrieve.
SQLPOINTER	`ValuePtr`	output	Pointer to a buffer in which to return the value of the attribute specified in `Attribute`.
SQLINTEGER	`BufferLength`	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, `BufferLength` is ignored. If `Attribute` is a DB2 CLI attribute, the application indicates the nature of the attribute by setting the `BufferLength` argument. `BufferLength` can have the following values: If `ValuePtr` is a pointer to a character string, then `BufferLength` is the length of the string or SQL_NTS. If `ValuePtr` is a pointer to a binary buffer, then the application places the result of the SQL_LEN_BINARY_ATTR(length) macro in `BufferLength`. If `ValuePtr` is a pointer to a value other than a character string or binary string, then `BufferLength` should have the value SQL_IS_POINTER. If `ValuePtr` contains a fixed-length data type, then `BufferLength` is either SQL_IS_INTEGER or SQL_IS_UINTEGER, as appropriate.
SQLSMALLINT	`*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 this 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 `BufferLength`, the data in `ValuePtr` is truncated to `BufferLength` minus the length of a null termination character and is null terminated by the DB2 CLI.

Usage

A call to SQLGetStmtAttr() returns in *ValuePtr the value of the statement 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 statement attributes can be retrieved by SQLGetStmtAttr(). For a description of the attributes, see SQLSetStmtAttr--Set options related to a statement.

SQL_ATTR_CURSOR_SCROLLABLE (DB2 CLI/ODBC)
SQL_ATTR_CURSOR_SENSITIVITY (DB2 CLI/ODBC)
SQL_ATTR_CURSOR_TYPE (DB2 CLI/ODBC)
SQL_ATTR_ROW_ARRAY_SIZE (DB2 CLI/ODBC)
SQL_ATTR_ROW_BIND_TYPE (DB2 CLI/ODBC)
SQL_ATTR_ROW_NUMBER (DB2 CLI/ODBC)
SQL_ATTR_DELETE_MODE (DB2 Everyplace)
SQL_ATTR_DIRTYBIT_SET_MODE (DB2 Everyplace)
SQL_ATTR_READ_MODE (DB2 Everyplace)
SQL_ATTR_REORG_MODE (DB2 Everyplace)

Return codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

ǥ 71. SQLGetStmtAttr SQLSTATEs

SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (Function returns SQL_SUCCESS_WITH_INFO.)
01004	Data truncated.	The data returned in `ValuePtr` is 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.)
24000	Invalid cursor state.	The argument `Attribute` is SQL_ATTR_ROW_NUMBER and the cursor is not open, or the cursor is positioned before the start of the result set or after the end of the result set.
HY000	General error.	An error occurred for which there is 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.
HY010	Function sequence error.	An asynchronously executing function is called for the `StatementHandle` and is still executing when this function is called. `SQLExecute()` or `SQLExecDirect()` is called for the `StatementHandle` and returned SQL_NEED_DATA. This function is called before data is sent for all data-at-execution parameters or columns.
HY013	Unexpected memory handling error.	DB2 CLI is unable to access memory required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The value specified for argument `BufferLength` is less than 0.
HY092	Option type out of range.	The value specified for the argument `Attribute` is not valid for this version of DB2 CLI
HY109	Invalid cursor position.	The `Attribute` argument is SQL_ATTR_ROW_NUMBER and the row had been deleted or could not be fetched.
HYC00	Driver not capable.	The value specified for the argument `Attribute` is a valid DB2 CLI attribute for the version of DB2 CLI, but is not supported by the data source.

Restrictions

None.

Related reference