Level 1 function

Return result data for a single column in the current row.

EDSGetData(HSTMT_IV, COLNUM_IV, ETYPE_IV,VALUE_SV |VALUE_IV |VALUE_FV, MAXBYTES_IV, NUMBYTES_IV )

•HSTMT_IV An input integer value that indicates the statement handle.

•COLNUM_IV An input integer value indicating the column number. (If your application has called EDSGetData for this result set, COLNUM_IV must be greater than or equal to the column number in the preceding call to EDSGetData.)

•ETYPE_IV An input integer value indicating the ESL data type to convert data into: EDS_STRING, EDS_INT, or EDS_FLOAT.

•VALUE_SV|VALUE_IV|VALUE_FV An output value into which the data is retrieved. The data must be in the form specified by ETYPE_IV.

•MAXBYTES_IV An input integer value indicating the maximum number of bytes that can be received by the VALUE argument in a single call to EDSGetData. MAXBYTES_IV cannot be greater than EDS_MAX_DATA (32K).

•NUMBYTES_IV An output reference integer value indicating the total number of bytes, or EDS_NO_TOTAL if the length cannot be determined in advance (see "Description," ). If NUMBYTES_IV is greater than EDS_MAX_DATA (32K), there is more data to fetch.

 

Description

Unlike EDSBindCol, which causes data to be transferred to a program variable when EDSFetch or EDSExtendedFetch is called, EDSGetData can only return result data for a single column in the current row. In other words, EDSFetch or EDSExtendedFetch moves the cursor to the next row and implicitly transfers data when EDSBindCol has been used, but EDSFetch or EDSExtendedFetch merely move the cursor to the next row then EDSGetData is used--the data is only transferred to the program variable when EDSGetData is called. It is possible to use EDSBindCol for some columns and use EDSGetData for others within the same row. This function can be used to retrieve long data values in portions.

Your application must call EDSFetch or EDSExtendedFetch before calling EDSGetData. EDSFetch positions the cursor at the next row and retrieves all bound columns. You can then call EDSGetData to retrieve data for specific unbound columns.

EDSExtendedFetch retrieves all bound columns for each row in the rowset and leaves the cursor positioned on the entire rowset.  Your application must then call EDSSetPos to position the cursor to a specific row. Finally, it can call EDSGetData to retrieve data for specific unbound columns. Note that not all drivers allow your application to use EDSExtendedFetch to retrieve more than one row of data and then return that data with EDSGetData.

Your application cannot call EDSGetData to retrieve a column that resides at or before the last bound column, if bound columns exist for the result set. When EDSGetData is called for more than one column in a given row of data, the column specified in each call to EDSGetData must be greater than or equal to the column specified in the preceding call.

If more than one call to EDSGetData is required to receive data for a single column, the driver returns EDS_SUCCESS_WITH_INFO. A subsequent call to EDSError returns SQLSTATE value 01004 (data truncated). Your application can then use the same column number for subsequent calls until EDSGetData returns EDS_SUCCESS, indicating that all data for the column has been retrieved. EDSGetData will return EDS_NO_DATA_FOUND when it is called for a column after all of the data has been retrieved and before data is retrieved for a subsequent column. Your application can ignore excess data by proceeding to the next result column.

With each call, the driver sets NUMBYTES_IV to the number of bytes that were available in the result column prior to the current call to EDSGetData. (If EDS_MAX_LENGTH has been set with EDSSetStmtOption, and the total number of bytes available on the first call is greater than EDS_MAX_LENGTH, the available number of bytes is set to EDS_MAX_LENGTH.) If the total number of bytes in the result set cannot be determined in advance, the driver sets NUMBYTES_IV to EDS_NO_TOTAL. If the data value for the column is NULL, the driver stores EDS_NULL_DATA in NUMBYTES_IV.

Return Values

EDSGetData returns EDS_SUCCESS, EDS_SUCCESS_WITH_INFO, EDS_NO_DATA_FOUND, EDS_INVALID_HANDLE, or EDS_ERROR.

When EDSGetData 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 EDSGetData.

The following table lists possible SQLSTATE values:

See Also

EDSBindCol binds a column to an ESL variable.

EDSExecDirect and EDSExecute execute a statement.

EDSFetch and EDSExtendedFetch advance the row pointer and fetch bound data associated with the row.