DB2 10.5 for Linux, UNIX, and Windows

SQLGetStmtAttr function (CLI) - Get current setting of a statement attribute

Returns the current setting of a statement attribute.

Specification:

CLI 5.0
ODBC 3.0
ISO CLI

Unicode equivalent: This function can also be used with the Unicode character set. The corresponding Unicode function is SQLGetStmtAttrW(). See Unicode functions (CLI) for information about ANSI to Unicode function mappings.

Syntax

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

Function arguments

Table 1. 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 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 number of bytes needed to store 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. If the value returned in ValuePtr is a Unicode string, the BufferLength argument must be an even number.
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 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 CLI returns the length of that string in the *StringLengthPtr buffer. If the value is a 32-bit value, the BufferLength and StringLengthPtr arguments are not used.

The following statement attributes are read-only, so can be retrieved by SQLGetStmtAttr(), but not set by SQLSetStmtAttr(). Refer to the list of statement attributes for all statement attributes that can be set and retrieved.

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 2. 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 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 about process-level memory limitations.
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 CLI
HY109	Invalid cursor position.	The Attribute argument was 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 was a valid CLI attribute for the version of CLI, but was not supported by the data source.

Restrictions

None.

Example

  /* get the handle for the implicitly allocated descriptor */
  rc = SQLGetStmtAttr(hstmt,
                      SQL_ATTR_IMP_ROW_DESC,
                      &hIRD,
                      SQL_IS_INTEGER,
                      &indicator);