Level 2 subroutine
Position a cursor within a fetched block of data.
call EDSSetPos(HSTMT_IV, ROW_IV, REFRESH_IV, LOCK_IV)
•HSTMT_IV An input integer value that indicates the statement handle.
•ROW_IV An input integer value indicating the absolute position of the cursor within the retrieved block of data. If ROW_IV equals EDS_ENTIRE_ROWSET, EDSSetPos sets the cursor to the entire rowset retrieved by EDSExtendedFetch. Subsequent positioned operations affect values in the entire rowset. Otherwise, ROW_IV must be a value from 1 to the number of rows in the rowset. For additional information about rowset size, refer to EDSSetScrollOptions.
•REFRESH_IV An input integer value that specifies whether to refresh the buffer value for the positioned row. If EDS_TRUE, the driver refreshes the buffer value. If EDS_FALSE, the driver does not change the buffered value.
•LOCK_IV An input integer value that specifies whether to lock the row for a subsequent update operation. If EDS_TRUE, the driver requests a lock for the row. If EDS_FALSE, the driver applies the form of concurrency control specified in a call to EDSSetScrollOptions.
Description
Before calling EDSSetPos, your application must call EDSExtendedFetch to retrieve a block of data. Locking works as follows:
To guarantee that a row will not change, set REFRESH_IV to EDS_TRUE and LOCK_IV to EDS_TRUE.
•If your application does not call EDSSetPos to lock the rows, the driver guarantees a positioned update or delete operation only if your application specifies EDS_CONCUR_LOCK in a call to EDSSetScrollOptions. This call must occur prior to calling EDSExtendedFetch.
•If your application requests EDS_CONCUR_TIMESTAMP or EDS_CONCUR_VALUES in a call to EDSSetScrollOptions, the driver compares timestamps or values, and rejects the operation if the row has changed since your application fetched the row.
•If your application requests EDS_CONCUR_READ_ONLY and did not lock the rows, the driver rejects any positioned update or delete operation.
Return Value
EDSSetPos returns EDS_SUCCESS, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSSetPos 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 EDSSetPos.
The following table lists possible SQLSTATE values:
SQL STATE |
Error |
Description |
24000 |
Invalid cursor state |
The previous SQL statement executed on the statement handle was not a SELECT statement. |
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. |
S1009 |
Invalid argument value |
The value specified for the argument REFRESH_IV was neither the defined constant TRUE nor the defined constant FALSE. The value specified for the argument LOCK_IV was neither the defined constant TRUE nor the defined constant FALSE. |
S1010 |
Function sequence error |
The function was called without first calling EDSExtendedFetch. An asynchronously executing function (not this one) was called for the statement handle and was still executing when this function was called. |
S1107 |
Row value out of range |
The value specified for the argument ROW_IV was greater than the number of rows in the rowset as specified by the ROWSET_IV argument in EDSSetScrollOptions. |
S1109 |
Invalid cursor |
The behavior of the cursor associated with the position; no keyset defined statement handle was defined as forward only. There was no keyset, so the cursor could not be positioned within the rowset. See the description for the KEYSET_IV argument in EDSSetScrollOptions. |
S1C00 |
Driver not capable |
The driver or data source does not support the refreshing of buffered rows. The driver or data source does not support row level locking for update operations. |
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
EDSExtendedFetch fetches a block of data from a result set.
EDSSetScrollOptions sets the number of rows received by EDSExtendedFetch.
