SQLExtendedFetch (level two only)
SQLExtendedFetch extends the functionality of SQLFetch.
- It returns row-set data (one or more rows), in the form of an array, for each bound column.
- It scrolls through the result set according to the setting of a scroll-type argument.
SQLExtendedFetch works with SQLSetStmtOption.
To fetch one row of data at a time in a forward direction, an application calls SQLFetch.
| SQLSTATE | Error value | Error message |
|---|---|---|
| 01000 | -11001 | General warning |
| 01004 | -11003 | Data truncated |
| 01S01 | -11006 | Error in row |
| 07006 | -11013 | Restricted data type attribute violation |
| 08S01 | -11020 | Communication-link failure |
| 22002 | -11024 | Indicator value required but not supplied |
| 22003 | -11025 | Numeric value out of range |
| 22005 | -11026 | Error in assignment |
| 22008 | -11027 | Datetime field overflow |
| 22012 | -11028 | Division by zero |
| 24000 | -11031 | Invalid cursor state |
| 40001 | -11037 | Serialization failure |
| S1000 | -11060 | General error |
| S1001 | -11061 | Memory-allocation failure |
| S1002 | -11062 | Invalid column number |
| S1008 | -11065 | Operation canceled |
| S1010 | -11067 | Function-sequence error |
| S1106 | -11086 | Fetch type out of range |
| S1107 | -11087 | Row value out of range |
| S1C00 | -11092 | Driver not capable |
| S1T00 | -11094 | Time-out expired |
| 08S01 | -11301 | A protocol error has been detected. Current connection is closed. |
| S1000 | -11307 | In SQLExtendedFetch, only SQL_FETCH_NEXT is supported for SQL_SCROLL_Forward_only cursors |
If an error occurs that pertains to the entire row set, such as SQLSTATE S1T00 (Time-out expired), the driver returns SQL_ERROR and the appropriate SQLSTATE. The contents of the row set buffers are undefined, and the cursor position is unchanged.
- Sets the element in the rgfRowStatus array for the row to SQL_ROW_ERROR
- Posts SQLSTATE 01S01 (Error in row) in the error queue
- Posts zero or more additional SQLSTATE values for the error after SQLSTATE 01S01 (Error in row) in the error queue
After the driver processes the error or warning, it continues the operation for the remaining rows in the row set and returns SQL_SUCCESS_WITH_INFO. Thus, for each error that pertains to a single row, the error queue contains SQLSTATE 01S01 (Error in row) followed by zero or more additional SQLSTATEs.
After the driver processes the error, it fetches the remaining rows in the row set and returns SQL_SUCCESS_WITH_INFO. Thus, for each row that returns an error, the error queue contains SQLSTATE 01S01 (Error in row) followed by zero or more additional SQLSTATE values.
If the row set contains rows that are already fetched, the driver is not required to return SQLSTATE values for errors that occurred when the rows were first fetched. However, it is required to return SQLSTATE 01S01 (Error in row) for each row in which an error originally occurred and to return SQL_SUCCESS_WITH_INFO. For example, a static cursor that maintains a cache might cache row-status information (so that it can determine which rows contain errors) but might not cache the SQLSTATE associated with those errors.
Error rows do not affect relative cursor movements. For example, suppose the result set size is 100, and the row-set size is 10. If the current row set is rows 11 through 20 and the element in the rgfRowStatus array for row 11 is SQL_ROW_ERROR, calling SQLExtendedFetch with the SQL_FETCH_NEXT fetch type still returns rows 21 through 30.
If the driver returns any warnings, such as SQLSTATE 01004 (Data truncated), it returns warnings that apply to the entire row set or to unknown rows in the row set before it returns error information that applies to specific rows. It returns warnings for specific rows with any other error information about those rows.