Call Level Interface Guide and Reference

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

Table 118. 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. This places a negative value 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 is 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.

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`. This places a negative value 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` is 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. That value can either be a 32-bit value or a null-terminated character string. If the value is a null-terminated string, the application specifies the maximum length of that string in the BufferLength argument, and DB2 CLI returns the length of that string in the *StringLengthPtrPtr buffer. If the value is a 32-bit value, the BufferLength and StringLengthPtr arguments are not used.

In order to allow DB2 CLI Version 5.2 applications calling SQLGetStmtAttr() to work with DB2 CLI Version 2, a call to SQLGetStmtAttr() is mapped to SQLGetStmtOption().

The following statement attributes are read-only, so can be retrieved by SQLGetStmtAttr(), but not set by SQLSetStmtAttr(). For a list of attributes that can be set and retrieved, see SQLSetStmtAttr - Set Options Related to a Statement.

SQL_ATTR_IMP_PARAM_DESC
SQL_ATTR_IMP_ROW_DESC
SQL_ATTR_ROW_NUMBER

Return Codes

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_ERROR
SQL_INVALID_HANDLE

Diagnostics

Table 119. SQLGetStmtAttr 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.)
24000 Invalid cursor state. The argument Attribute was SQL_ATTR_ROW_NUMBER and the cursor was not open, or the cursor was 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 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. An asynchronously executing function was called for the StatementHandle and was still executing when this function was called.
SQLExecute() or SQLExecDirect() was called for the StatementHandle and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
HY013 Unexpected memory handling error. DB2 CLI was 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 was less than 0.
HY092 Option type out of range. The value specified for the argument Attribute was not valid for this version of DB2 CLI
HY109 Invalid cursor position. The Attribute argument was SQL_ATTR_ROW_NUMBER and the the row had been deleted or could not be fetched.
HYC00 Driver not capable. The value specified for the argument Attribute was a valid DB2 CLI attribute for the version of DB2 CLI, 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 length of the untruncated string value is returned in `StringLengthPtr`. (Function returns SQL_SUCCESS_WITH_INFO.)
24000	Invalid cursor state.	The argument `Attribute` was SQL_ATTR_ROW_NUMBER and the cursor was not open, or the cursor was 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 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.	An asynchronously executing function was called for the `StatementHandle` and was still executing when this function was called. `SQLExecute()` or `SQLExecDirect()` was called for the `StatementHandle` and returned SQL_NEED_DATA. This function was called before data was sent for all data-at-execution parameters or columns.
HY013	Unexpected memory handling error.	DB2 CLI was 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` was less than 0.
HY092	Option type out of range.	The value specified for the argument `Attribute` was not valid for this version of DB2 CLI
HY109	Invalid cursor position.	The `Attribute` argument was SQL_ATTR_ROW_NUMBER and the the row had been deleted or could not be fetched.
HYC00	Driver not capable.	The value specified for the argument `Attribute` was a valid DB2 CLI attribute for the version of DB2 CLI, 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 ]