`SQLGetStmtAttr()` - Get current setting of a statement attribute

SQLGetStmtAttr() returns the current setting of a statement attribute. To set these statement attributes, use SQLSetStmtAttr().

ODBC specifications for `SQLGetStmtAttr()`

Table 1. `SQLGetStmtAttr()` specifications
ODBC specification level	In X/Open CLI CAE specification?	In ISO CLI specification?
3.0	Yes	Yes

Syntax

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

Function arguments

The following table lists the data type, use, and description for each argument in this function.

Table 2. `SQLGetStmtAttr()` arguments
Data type	Argument	Use	Description
SQLHSTMT	StatementHandle	input	Specifies a connection handle.
SQLINTEGER	Attribute	input	Specifies the statement attribute to retrieve. For a complete list of these attributes, refer to the function `SQLSetStmtAttr()`.
SQLPOINTER	ValuePtr	output	Points to a buffer in which to return the current value of the attribute specified by the Attribute argument. The value that is returned into this buffer is a 32-bit unsigned integer value or a nul-terminated character string. If the a driver-specific value is specified for the Attribute argument, a signed integer might be returned.
SQLINTEGER	BufferLength	input	The value that you specify for this argument depends which of the following types of attributes you query: For ODBC-defined attributes: If the ValuePtr argument points to a character string, the BufferLength argument specifies the length (in bytes) of the buffer to which the ValuePtr argument points. If the ValuePtr argument points to an integer, the BufferLength argument is ignored. For driver-defined attributes (IBM® extension): If the ValuePtr argument points to a character string, the BufferLength argument specifies the length (in bytes) of the buffer to which the ValuePtr argument points, or specifies SQL_NTS for nul-terminated strings. If SQL_NTS is specified, the driver assumes the length of buffer to which the ValuePtr argument points to be SQL_MAX_OPTIONS_STRING_LENGTH bytes (which excludes the nul-terminator). If the ValuePtr argument points to an integer, the BufferLength argument is ignored.
SQLINTEGER *	StringLengthPtr	output	Points to a buffer in which to return the total number of bytes (excluding the number of bytes returned for the nul-termination character) available to return in the buffer to which the ValuePtr argument points. If the ValuePtr argument specifies a null pointer, no length is returned. If the attribute value to which ValuePtr points 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 nul-termination character and is nul-terminated by Db2 ODBC. If the Attribute argument does not denote a string, Db2 ODBC ignores the BufferLength argument and does not return a value in the buffer to which the StringLengthPtr argument points.

Usage

SQLGetStmtAttr() returns the current setting of a statement attribute. You set these attributes using the SQLSetStmtAttr() function.

Return codes

After you call SQLGetStmtAttr(), it returns one of the following values:

SQL_SUCCESS
SQL_SUCCESS_WITH_INFO
SQL_INVALID_HANDLE
SQL_ERROR

Diagnostics

The following table lists each SQLSTATE that this function generates, with a description and explanation for each value.

Table 3. `SQLGetStmtAttr()` SQLSTATEs
SQLSTATE	Description	Explanation
01000	Warning.	Informational message. (`SQLGetStmtAttr()` returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
01004	Data truncated.	The data that is returned in the buffer to which the ValuePtr argument points is truncated to be the length (in bytes) of the value that the BufferLength argument specifies, minus the length of a nul-terminator. The length (in bytes) of the untruncated string value is returned in the buffer to which the StringLengthPtr argument points. (`SQLGetStmtAttr()` returns SQL_SUCCESS_WITH_INFO for this SQLSTATE.)
HY000	General error.	An error occurred for which no specific SQLSTATE exists. The error message that `SQLGetDiagRec()` returns describes the specific error and the cause of that error.
HY001	Memory allocation failure.	Db2 ODBC can not allocate memory that is required to support execution or completion of the function.
HY010	Function sequence error.	`SQLExecute()` or `SQLExecDirect()` is called on the statement handle and returns SQL_NEED_DATA. This function is called before data is sent for all data-at-execution parameters or columns. Invoke `SQLCancel()` to cancel the data-at-execution condition.
HY013	Unexpected memory handling error.	Db2 ODBC is not able to access memory that is required to support execution or completion of the function.
HY090	Invalid string or buffer length.	The value specified for the BufferLength argument is less than 0.
HY092	Option type out of range.	The value specified for the Attribute argument is not valid for this version of Db2 ODBC.
HYC00	Driver not capable.	The value specified for the Attribute argument is a valid connection or statement attribute for the version of the Db2 ODBC driver, but is not supported by the data source.

Example

The following example uses SQLGetStmtAttr() to retrieve the current value of a statement attribute:

SQLINTEGER cursor_hold;
rc = SQLGetStmtAttr( hstmt, SQL_ATTR_CURSOR_HOLD,
                                                        &cursor_hold, 0, NULL ) ;
CHECK_HANDLE( SQL_HANDLE_STMT, hstmt, rc ) ;
printf( "\nCursor With Hold is: " ) ;
if ( cursor_hold == SQL_CURSOR_HOLD_ON )
  printf( "ON\n" ) ;
else
  printf( "OFF\n" ) ;

SQLGetStmtAttr() - Get current setting of a statement attribute

ODBC specifications for SQLGetStmtAttr()