Core subroutine
Fetch a row of data from a result set.
call EDSFetch(HSTMT_IV )
•HSTMT_IV An input integer value that indicates the statement handle.
Description
EDSFetch advances the cursor to the next row. If your application called EDSBindCol to bind columns, EDSFetch stores data into the ESL variables specified by the calls to EDSBindCol.
EDSFetch is valid only after a call that returns a result set.
The driver manages cursors during the fetch operation and places each value of a bound column into the associated ESL variable. The driver follows these guidelines when performing a fetch operation:
•EDSFetch accesses column data in left-to-right order.
•After each fetch, NUMBYTES_IV (specified in EDSBindCol) contains the actual number of bytes in the result column. (If EDS_MAX_LENGTH has been specified with EDSSetStmtOption and the actual number of bytes in the result column is greater than EDS_MAX_LENGTH, NUMBYTES_IV contains EDS_MAX_LENGTH.)
•If the VALUE argument specified in EDSBindCol is not large enough to hold the entire result, the driver stores part of the value and returns EDS_SUCCESS_WITH_INFO. A subsequent call to EDSError indicates that a truncation occurred. Your application can compare MAXBYTES_IV to NUMBYTES_IV (both of which are specified in EDSBindCol) to determine which column or columns were truncated. If NUMBYTES_IV is greater than or equal to MAXBYTES_IV, then truncation occurred.
•If the data value for the column is NULL, the driver stores EDS_NULL_DATA in NUMBYTES_IV.
When finished with the result set, the driver returns EDS_NO_DATA_FOUND.
Your application can call EDSGetData to retrieve data that is not bound to an ESL variable. If your application does not call EDSBindColto bind any columns, EDSFetch does not return any data; it simply moves the cursor to the next row.
For information about conversions allowed by EDSBindCol and EDSGetData, refer to Data Types.
Return Values
EDSFetch returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_INVALID_HANDLE, EDS_ERROR, or EDS_NO_DATA_FOUND.
When EDSFetch 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 EDSFetch.
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 |
The 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. |
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 statement. |
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 the 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. |
S1C00 |
Driver not capable |
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 assign an ESL variable for result columns.
EDSCancel and EDSFreeStmt discard result sets.
EDSExecute and EDSExecDirect execute a SQL statement.
EDSExtendedFetch handles blocks of array rows.
EDSGetData returns a column with a large data value.
EDSNumResultCols and EDSDescribeCol list information about the result set.
EDSPrepare prepares a SQL statement prior to execution.
EDSSetScrollOptions supports scrollable cursors.
