SQLGetStmtAttr

Conformance

Version Introduced:ODBC 3.0
Standards Compliance:ISO 92

Summary

SQLGetStmtAttr returns the current setting of a statement attribute.

Note For more information about what the Driver Manager maps this function to when an ODBC 3.x application is working with an ODBC 2.x driver, see “Mapping Replacement Functions for Backward Compatibility of Applications” in Chapter 17, “Programming Considerations.”

Syntax

SQLRETURN SQLGetStmtAttr(
SQLHSTMTStatementHandle,
SQLINTEGERAttribute,
SQLPOINTERValuePtr,
SQLINTEGERBufferLength,
SQLINTEGER *StringLengthPtr);

Arguments

StatementHandle

[Input]
Statement handle.

Attribute

[Input]
Attribute to retrieve.

ValuePtr

[Output]
Pointer to a buffer in which to return the value of the attribute specified in Attribute.

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 the value returned in *ValuePtr is a Unicode string (when calling SQLGetStmtAttrW), the BufferLength argument must be an even number

If Attribute is a driver-defined attribute, the application indicates the nature of the attribute to the Driver Manager 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.

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 ValuePtr 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 driver.

Returns

SQL_SUCCESS, SQL_SUCCESS_WITH_INFO, SQL_ERROR, or SQL_INVALID_HANDLE.

Diagnostics

When SQLGetStmtAttr returns SQL_ERROR or SQL_SUCCESS_WITH_INFO, an associated SQLSTATE value may be obtained by calling SQLGetDiagRec with a HandleType of SQL_HANDLE_STMT and a Handle of StatementHandle. The following table lists the SQLSTATE values commonly returned by SQLGetStmtAttr and explains each one in the context of this function; the notation “(DM)” precedes the descriptions of SQLSTATEs returned by the Driver Manager. The return code associated with each SQLSTATE value is SQL_ERROR, unless noted otherwise.

Comments

For general information about statement attributes, see “Statement Attributes” in Chapter 9, “Executing Statements.”

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 the driver 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.

To allow applications calling SQLGetStmtAttr to work with ODBC 2.x drivers, a call to SQLGetStmtAttr is mapped in the Driver Manager 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.

Related Functions