Level 2 subroutine
Set options that control the behavior of cursors.
call EDSSetScrollOptions(HSTMT_IV, CONCURRENCY_IV, KEYSET_IV, ROWSET_IV)
•HSTMT_IV An input integer value that indicates the statement handle.
•CONCURRENCY_IV An input integer value that specifies concurrency control for the cursor and must be one of the values listed under "Description," below.
•KEYSET_IV An input integer value that indicates the number of rows for which to buffer keys. This value must be greater than or equal to ROWSET_IV or one of the following constants:
EDS_SCROLL_FORWARD_ONLY: the cursor behaves as a forward-only scrolling cursor.
EDS_SCROLL_KEYSET_DRIVEN: the driver keeps the key for every row retrieved.
EDS_SCROLL_DYNAMIC: the driver sets KEYSET_IV to the value of ROWSET_IV.
If KEYSET_IV is a value greater than ROWSET_IV, the value defines the number of rows in the keyset that are to be buffered by the driver. This reflects a mixed scrollable cursor; the cursor is keyset driven within the keyset and dynamic outside of the keyset.
•ROWSET_IV An input integer value that indicates the number of rows in a rowset. ROWSET_IV defines the number of rows fetched by each call to EDSExtendedFetch; this is the number of rows that your application buffers.
Description
EDSSetScrollOptions allows you to set options that control the behavior of cursors associated with statement handle you specify. You can determine the type of cursor behavior desired in three areas: concurrency control, sensitivity to changes made by other transactions, and array fetching.
The ESL application must call EDSSetScrollOptions before it calls EDSPrepare or EDSExecDirect. Your application must specify a buffer in a call to EDSBindCol that is large enough to hold the number of rows specified in ROWSET_IV.
If your application does not call EDSSetScrollOptions, ROWSET_IV has a default value of 1, KEYSET_IV has a default value of EDS_SCROLL_FORWARD_ONLY, and CONCURRENCY_IV equals EDS_CONCUR_READ_ONLY.
The following table lists valid concurrency control options.
Value |
Description |
EDS_CONCUR_READ_ONLY |
Cursor is read-only. No updates are allowed. |
EDS_CONCUR_LOCK |
Cursor uses intent-to-update locks. |
EDS_CONCUR_TIMESTAMP |
Cursor uses optimistic concurrency control, comparing timestamps. |
EDS_CONCUR_VALUES |
Cursor uses optimistic concurrency control, comparing values. |
Return Value
EDSSetScrollOptions returns EDS_SUCCESS, EDS_INVALID_HANDLE, or EDS_ERROR.
When EDSSetScrollOptions 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 EDSSetScrollOptions.
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. |
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. |
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 in a prepared or executed state. The function must be called before calling EDSPrepare or EDSExecDirect. |
S1107 |
Row value out of range |
The value specified for the argument ROWSET_IV was 0. |
S1108 |
Concurrency option out of range |
The value specified for the argument CONCURRENCY_IV was not equal to EDS_CONCUR_READ_ONLY, EDS_CONCUR_LOCK, EDS_CONCUR_TIMESTAMP, or EDS_CONCUR_VALUES. |
S1C00 |
Driver not capable |
The driver or data source does not support the concurrency control option specified in the argument CONCURRENCY_IV. The driver or data source does not support row level locking for update operations. |
See Also
EDSSetPos sets the cursor position within a fetched array.
EDSExtendedFetch fetches one rowset of data from the result set.
EDSBindCol defines an ESL variable for a column in a result set.
