What the Driver Does

The following table summarizes what functions and statement attributes an ODBC 3.x driver should implement for block and scrollable cursors.

Function or
statement attribute
Comments
SQL_ATTR_ROW_
STATUS_PTR		 Sets the address of the row status array filled by SQLFetch and SQLFetchScroll. This array is also filled by SQLSetPos if SQLSetPos is called in statement state S6. If SQLSetPos is called in state S7, this array is not filled, but the array pointed to by the RowStatusArray argument of SQLExtendedFetch is filled. For more information, see “Statement Transitions” in Appendix B, “ODBC State Transition Tables.”
SQL_ATTR_ROWS_
FETCHED_PTR		 Sets the address of the buffer in which SQLFetch and SQLFetchScroll return the number of rows fetched. If SQLExtendedFetch is called, this buffer is not filled, but the RowCountPtr argument points to the number of rows fetched.
SQL_ATTR_
ROW_ARRAY_SIZE		 Sets the rowset size used by SQLFetch and SQLFetchScroll.
SQL_ROWSET_SIZE Sets the rowset size used by SQLExtendedFetch. ODBC 3.x drivers implement this if they want to work with ODBC 2.x applications that call SQLExtendedFetch or SQLSetPos.
SQLBulkOperations If an ODBC 3.x driver should work with ODBC 2.x applications that use SQLSetPos with an Operation of SQL_ADD, then the driver must support SQLSetPos with an Operation of SQL_ADD in addition to SQLBulkOperations with an Operation of SQL_ADD.
SQLExtendedFetch Returns the specified rowset. ODBC 3.x drivers implement this if they want to work with ODBC 2.x applications that call SQLExtendedFetch or SQLSetPos. The following are implementation details:
  • The driver retrieves the rowset size from the value of the SQL_ROWSET_SIZE statement attribute.

  • The driver retrieves the address of the row status array from the RowStatusArray argument, not the SQL_ATTR_ROW_STATUS_PTR statement attribute. The RowStatusArray argument in a call to SQLExtendedFetch must not be a null pointer. (Note that in ODBC 3.x, the SQL_ATTR_ROW_STATUS_PTR statement attribute can be a null pointer.)

  • The driver retrieves the address of the rows fetched buffer from the RowCountPtr argument, not the SQL_ATTR_ROWS_FETCHED_PTR statement attribute.

  • The driver returns SQLSTATE 01S01 (Error in row) to indicate that an error has occurred while rows were fetched by a call to SQLExtendedFetch. An ODBC 3.x driver should return SQLSTATE 01S01 (Error in row) only when SQLExtendedFetch is called, not when SQLFetch or SQLFetchScroll is called. When SQLSTATE 01S01 (Error in row) is returned by SQLExtendedFetch, the Driver Manager does not order status records in the error queue according to the rules stated in the “Sequence of Status Records” section of SQLGetDiagField, to preserve backward compatibility.
SQLFetch Returns the next rowset. The following are implementation details:
  • The driver retrieves the rowset size from the value of the SQL_ATTR_ROW_ARRAY_SIZE statement attribute.

  • The driver retrieves the address of the row status array from the SQL_ATTR_ROW_STATUS_PTR statement attribute.

  • The driver retrieves the address of the rows fetched buffer from the SQL_ATTR_ROWS_FETCHED_PTR statement attribute.

  • The application can mix calls between SQLFetchScroll and SQLFetch.

  • SQLFetch returns bookmarks if column 0 is bound.

  • SQLFetch can be called to return more than one row.

  • The driver does not return SQLSTATE 01S01 (Error in row) to indicate that an error has occurred while rows were fetched by a call to SQLFetch.
SQLFetchScroll Returns the specified rowset. The following are implementation details:
  • The driver retrieves the rowset size from the SQL_ATTR_ROW_ARRAY_SIZE statement attribute.

  • The driver retrieves the address of the row status array from the SQL_ATTR_ROW_STATUS_PTR statement attribute.

  • The driver retrieves the address of the rows fetched buffer from the SQL_ATTR_ROWS_FETCHED_PTR statement attribute.

  • The application can mix calls between SQLFetchScroll and SQLFetch.

  • The driver does not return SQLSTATE 01S01 (Error in row) to indicate that an error has occurred while rows were fetched by a call to SQLFetchScroll.
SQLSetPos Performs various positioned operations. The following are implementation details:
  • This can be called in statement states S6 or S7. For more details, see “Statement Transitions” in Appendix B, “ODBC State Transition Tables.”

  • If this is called in statement state S5 or S6, the driver retrieves the rowset size from the SQL_ATTR_ROWS_FETCHED_PTR statement attribute and the address of the row status array from the SQL_ATTR_ROW_STATUS_PTR statement attribute.

  • If this is called in statement state S7, the driver retrieves the rowset size from the SQL_ROWSET_SIZE statement attribute and the address of the row status array from the RowStatusArray argument of SQLExtendedFetch.

  • The driver only returns SQLSTATE 01S01 (Error in row) to indicate that an error has occurred while rows were fetched by a call to SQLSetPos to perform a bulk operation when the function is called in state S7. If SQLSTATE 01S01 (Error in row) is returned by SQLSetPos, the Driver Manager does not order status records in the error queue according to the rules stated in the “Sequence of Status Records” section of SQLGetDiagField, to preserve backward compatibility.

  • If the driver should work with ODBC 2.x applications that call SQLSetPos with an Operation argument of SQL_ADD, the driver must support SQLSetPos with an Operation argument of SQL_ADD.