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);