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