Level 2 subroutine
Extend the functionality of EDSFetch.
call EDSExtendedFetch(HSTMT_IV,FETCHTYPE_IV,IROW_IV,NUMROWS_IV, ARRAY_STRUCT)
•HSTMT_IV An input integer value that indicates the statement handle.
•FETCHTYPE_IV An input integer value that indicates the type of fetch, as listed in the table on the next page.
•IROW_IV An input integer value that indicates the number of the row to fetch. Valid only when FETCHTYPE_IV is EDS_FETCH_ABSOLUTE or EDS_FETCH_RELATIVE. Otherwise, it is ignored.
•NUMROWS_IV An output integer value that indicates the number of rows actually fetched. If an error occurs during processing, NUMROWS_IV contains the row that precedes the row with the error.
•ARRAY_STRUCT An output integer value that contains an array of status values. The number of elements must equal ROWSET_IV, as defined in a call to EDSSetScrollOptions. The driver returns a status value for each row fetched. These status values can equal EDS_ROW_SUCCESS, EDS_ROW_DELETED, or EDS_ROW_UPDATED.
Description
EDSExtendedFetch extends the functionality of EDSFetch in the following ways:
•Returns a block of data (one rowset), in the form of an array, for each bound column
•Scrolls through the result set according to the setting of a scroll-type argument—forwards, backwards, or by row number.
EDSExtendedFetch works in conjunction with EDSSetScrollOptions. The block of data contains the number of rows indicated by the ROWSET_IV argument in EDSSetScrollOptions. Immediately after the fetch, the driver leaves the cursor positioned on the first row of the rowset. To fetch one row of data at a time in a forward direction, use EDSFetch.
Valid values for FETCHTYPE_IV depend on the fetch capabilities defined for the driver and can be determined by calling EDSGetInfo with the EDS_FETCH_DIRECTION option. The following table lists all valid values.
FETCHTYPE_IV |
Description |
EDS_FETCH_NEXT |
Fetch the next rowset. |
EDS_FETCH_FIRST |
Fetch the first rowset. |
EDS_FETCH_LAST |
Fetch the last rowset. |
EDS_FETCH_PREV |
Fetch the previous rowset. |
EDS_FETCH_ABSOLUTE |
Fetch the rowset starting with row IROW_IV. |
EDS_FETCH_RELATIVE |
Fetch the rowset starting with IROW_IV rows from the first row in the current rowset. |
EDS_FETCH_RESUME |
Fetch the remainder of a rowset that received an error and was partially retrieved. |
The status array allows your application to detect rows in the rowset that have been deleted (EDS_ROW_DELETED) or rows that have changed (EDS_ROW_UPDATED). A driver can detect changes only if the row that has been fetched again is in the current keyset. If the row has not changed, or the driver cannot detect whether it has changed, the driver sets the status value to EDS_ROW_SUCCESS. Note that some drivers cannot detect any changes. To determine whether a driver can detect changes to rows fetched with EDSExtendedFetch, your application can call EDSGetInfo with the EDS_ROW_UPDATES option.
If the number of rows fetched is less than the number of elements in the status array, the driver sets remaining status elements to EDS_ROW_NOROW. If the number of rows fetched is greater than the number of elements in the status array, EDS returns with a return value of EDS_RESIZE_ARRAY, without performing any fetches. You have the option of resizing the array and calling the fetch again.
If an error occurs during the fetch of a rowset, EDSExtendedFetch returns EDS_ERROR and an associated error value. The driver sets NUMROWS_IV to the number of rows actually fetched. The next row contains an error. To finish processing the rowset, your application can resolve the error and call EDSExtendedFetch with EDS_FETCH_RESUME.
The update of a key value is interpreted as the deletion of the underlying row and the addition of a new row.
When a fetch would move beyond the beginning or end of the result set using EDS_FETCH_NEXT, EDS_FETCH_PREV, or EDS_FETCH_RELATIVE, the driver returns EDS_NO_DATA_FOUND. This is also true for EDS_FETCH_ABSOLUTE when IROW_IV is not 0.
EDSExtendedFetch supports column-wise binding of query results to ESL variables specified in EDSBindCol.
For each bound column specified by EDSBindCol, your application must provide an array whose size is the number of rows specified by ROWSET_IV in EDSSetScrollOptions. Therefore, the VALUE argument in EDSBindCol must be an array of ESL variables of type ETYPE_IV.
In addition to the array of variables for column data, the application must also provide an array of INTEGER values to hold the value for the actual number of bytes returned for the column for each of the number of rows specified by ROWSET_IV in EDSSetScrollOptions. Therefore, the NUMBYTES_IV argument in EDSBindCol must be an array of ESL integer variables.
Return Values
EDSExtendedFetch returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_NO_DATA_FOUND, EDS_RESIZE_ARRAY, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSExtendedFetch returns EDS_ERROR, you can obtain an associated SQLSTATE value with more specific information by calling EDSError. The following table lists each typical SQLSTATE value and explains each one in the context of the command EDSExtendedFetch.
The following table lists possible SQLSTATE values.
SQL STATE |
Error |
Description |
01004 |
Data truncated |
The data returned for one or more columns was truncated. String values are right truncated. For numeric values, the fractional part of the number was truncated. (Function returns EDS_SUCCESS_WITH_INFO.) |
07006 |
Restricted data type attribute violation |
A data value could not be converted to the data type specified by ETYPE_IV in EDSBindCol. |
08S01 |
Communication link failure |
The communication link between the driver and the data source to which the driver was connected failed before the function completed processing. |
22003 |
Numeric value out of range |
Returning the numeric value (as numeric or string) for one or more columns would have caused the whole part of the number to be truncated. Returning the binary value for one or more columns would have caused a loss of binary significance. |
22012 |
Division by zero |
A value from an arithmetic expression was returned which resulted in division by zero. |
24000 |
Invalid cursor state |
The previous SQL statement executed on the statement handle was not a SELECT. |
40001 |
Serialization failure |
The transaction in which the fetch was executed was terminated to prevent deadlock. |
IM001 |
Driver does not support this function |
The driver associated with the statement handle does not support the function. |
S1000 |
General error |
An error occurred for which there was no specific SQLSTATE and for which no implementation-specific SQLSTATE was defined. The error message returned by EDSError in the argument ERRORTEXT describes the error and its cause. |
S1001 |
Memory allocation failure |
The driver was unable to allocate memory required to support execution or completion of the function. |
S1002 |
Invalid column number |
A column number specified in the binding for one or more columns was greater than the number of columns in the result set. |
S1008 |
Operation cancelled |
Asynchronous processing was enabled for the statement handle. The function was called and before it completed execution, EDSCancel was called on the statement handle. Then the function was called again on the statement handle. |
S1010 |
Function sequence error |
The specified statement handle was not in an executed state. The function was called without first calling EDSExecute or EDSExecDirect. An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1106 |
Fetch type out of range |
The value specified for the argument FETCHTYPE_IV was not equal to: EDS_FETCH_NEXT EDS_FETCH_FIRST EDS_FETCH_LAST EDS_FETCH_PREV EDS_FETCH_ABSOLUTE EDS_FETCH_RELATIVE EDS_FETCH_RESUME |
S1107 |
Row value out of range |
The fetch type was specified as EDS_FETCH_ABSOLUTE and the value specified for the argument IROW_IV was equal to 0. |
S1C00 |
Driver not capable |
Driver or data source does not support the specified fetch type. The driver or data source does not support the conversion specified by the combination of the ETYPE_IV in EDSBindCol and the SQL data type of the corresponding column. |
S1T00 |
Timeout expired |
The timeout period expired before the data source returned the result set. The timeout period is set through EDSSetStmtOption, EDS_QUERY_TIMEOUT. |
See Also
EDSBindCol assigns an ESL variable to a column in a result set.
EDSDescribeCol returns information about a column in a result set.
EDSExecute executes a prepared statement.
EDSNumResultCols returns the number of columns in a result set.
EDSSetPos sets cursor position within a fetched array.
EDSSetScrollOptions specifies the number of rows to fetch.
EDSSetStmtOption sets a statement option.
