SQLGetStmtAttr - Get the value of a statement attribute

SQLGetStmtAttr() returns the current settings of the specified statement attribute.

These options are set using the SQLSetStmtAttr() function. This function is similar to SQLGetStmtOption(). Both functions are supported for compatibility reasons.

Unicode (UTF-16) equivalent: This function can also be used with the Unicode (UTF-16) character set. The corresponding Unicode function is SQLGetStmtAttrW(). Refer to Unicode in Db2 for i CLI for more information about Unicode support for DB2® CLI.

Syntax

SQLRETURN SQLGetStmtAttr( SQLHSTMT        hstmt,
                            SQLINTEGER    fAttr,
                            SQLPOINTER    pvParam,
                            SQLINTEGER    bLen,
                            SQLINTEGER    *sLen);

Function arguments

Table 1. SQLGetStmtAttr arguments
Data type Argument Use Description
SQLHSTMT hstmt Input Statement handle.
SQLINTEGER fAttr Input Attribute to retrieve. Refer to Table 2 for more information.
SQLPOINTER pvParam Output Pointer to buffer for requested attribute.
SQLINTEGER bLen Input Maximum number of bytes to store in pvParam, if the attribute is a character string; otherwise, unused.
SQLINTEGER * sLen Output Length of output data if the attribute is a character string; otherwise, unused.

Usage

Table 2. Statement attributes
fAttr Data type Contents
SQL_ATTR_APP_PARAM_DESC Integer The descriptor handle used by the application to provide parameter values for this statement handle.
SQL_ATTR_APP_ROW_DESC Integer The descriptor handle for the application to retrieve row data using the statement handle.
SQL_ATTR_CURSOR_SCROLLABLE Integer A 32-bit integer value that specifies if cursors opened for this statement handle should be scrollable.
  • SQL_FALSE – Cursors are not scrollable, and SQLFetchScroll() cannot be used against them.
  • SQL_TRUE – Cursors are scrollable. SQLFetchScroll() can be used to retrieve data from these cursors.
SQL_ATTR_CURSOR_TYPE Integer A 32-bit integer value that specifies the behavior of cursors opened for this statement handle.
  • SQL_CURSOR_FORWARD_ONLY – Cursors are not scrollable, and SQLFetchScroll() cannot be used against them.
  • SQL_DYNAMIC – Cursors are scrollable. SQLFetchScroll() can be used to retrieve data from these cursors.
SQL_ATTR_CURSOR_SENSITIVITY Integer The cursor sensitivity.
  • SQL_UNSPECIFIED – Cursors on the statement handle might make visible none, some, or all such changes depending on the cursor type.
  • SQL_INSENSITIVE – All valid cursors on the statement handle show the result set without reflecting any changes made to it by any other cursor.
  • SQL_SENSITIVE – All valid cursors on the statement handle make visible all changes made to a result by another cursor.
SQL_ATTR_CURSOR_HOLD Integer Returns the HOLDABILITY for the cursor for the statement.
  • SQL_FALSE – Cursor position is not held across transaction boundaries.
  • SQL_TRUE – Cursor position is held across transaction boundaries.
SQL_ATTR_FOR_FETCH_ONLY Integer This indicates if cursors opened for this statement handle should be read-only.
  • SQL_FALSE - Cursors can be used for positioned updates and deletes. This is the default.
  • SQL_TRUE - Cursors are read-only and cannot be used for positioned updates or deletes.
SQL_ATTR_IMP_PARAM_DESC Integer The descriptor handle used by the CLI implementation to provide parameter values for this statement handle.
SQL_ATTR_IMP_ROW_DESC Integer The descriptor handle used by the CLI implementation to retrieve row data using this statement handle.
SQL_ATTR_ROWSET_SIZE Integer A 32–bit integer value that specifies the number of rows in the rowset. This is the number of rows returned by each call to SQLExtendedFetch(). The default value is 1.
SQL_ATTR_PARAM_BIND_TYPE Integer The binding used for the parameters.
  • SQL_BIND_BY_ROW - Binding is row-wise. This is the default. When using row-wise binding for a multiple row statements, all of the data for each row must be contiguous storage, followed by the data for the next row, and so on.
  • SQL_BIND_BY_COLUMN - Binding is column-wise. When using column-wise binding for a multiple row statements, all of the data for each column is in contiguous storage. A different address is provided by the user for each column in the statement, and it is the responsibility of the user to ensure that each address has space for all the parameter data to be passed to the database.
SQL_ATTR_ROW_BIND_TYPE Integer The binding used for rows.
  • SQL_BIND_BY_ROW - Binding is row-wise. When using row-wise binding for a multiple row fetch, all of the data for a row is returned in contiguous storage, followed by the data for the next row, and so on.
  • SQL_BIND_BY_COLUMN - Binding is column-wise. When using column-wise binding for a multiple row fetch, all of the data for each column is returned in contiguous storage. The storage for each column need not be contiguous. A different address is provided by the user for each column in the result set, and it is the responsibility of the user to ensure that each address has space for all the data to be retrieved.
SQL_ATTR_PARAMSET_SIZE Integer Returns the number of rows for each multiple row statement. These include INSERT, MERGE, and UPDATE statements.

Return codes

  • SQL_SUCCESS
  • SQL_SUCCESS_WITH_INFO
  • SQL_ERROR
  • SQL_INVALID_HANDLE
  • SQL_NO_DATA

Diagnostics

Table 3. SQLGetStmtAttr SQLSTATEs
SQLSTATE Description Explanation
HY001 Memory allocation failure The driver is unable to allocate memory required to support the processing or completion of the function.
HY009 Argument value that is not valid The argument pvParam is a null pointer.

An fAttr that is not valid value is specified.
HYC00 Driver not capable Db2 for i CLI recognizes the option but does not support it.