A typical application uses the steps below to declare and open a Client-Library cursor.
Send a cursor-declare command.
For cursors declared with a select statement:
ct_cursor(CS_CURSOR_DECLARE)
ct_param or ct_setparam to define host variable formats
ct_send (if not batching commands)
ct_results, in a loop (if not batching commands)
For cursors declared with an execute statement:
ct_cursor(CS_CURSOR_DECLARE)
ct_send (if not batching commands)
ct_results, in a loop (if not batching commands)
For cursors declared with a prepared dynamic SQL statement:
ct_dynamic(CS_CURSOR_DECLARE)
(Optional) ct_cursor(CS_CURSOR_OPTION)
ct_send
ct_results, in a loop
If a cursor is declared with a ct_cursor command, the commands in steps 1, 2, and 3 can be batched: they can be sent to the server with a single call to ct_send.
(Optional) Send a cursor-rows command.
ct_cursor(CS_CURSOR_ROWS)
ct_send (if not batching commands)
ct_results, in a loop (if not batching commands)
Send a cursor-open command.
ct_cursor(CS_CURSOR_OPEN)
ct_param or ct_setparam to pass parameter values
ct_send
ct_results, called in a standard results loop.
A successful open command returns a CS_CURSOR_RESULT result set. If batching commands, several calls to ct_results are required (to retrieve the status results from the batched commands) before the cursor rows are available.
Process cursor rows.
ct_bind to bind to cursor rows
ct_fetch or ct_scroll_fetch (called in a loop to retrieve each row)
New commands can be sent inside the ct_fetch or ct_scroll_fetch loop, after at least one row has been fetched. See “Step 4: Process cursor rows” for more information.
Close the cursor.
ct_cursor(CS_CURSOR_CLOSE)
ct_send
ct_results
An application can close and deallocate the cursor with one command by setting the CS_DEALLOC bit in the ct_cursor option parameter when defining the cursor-close command. In that case, the step 6 is unnecessary.
Deallocate the cursor.
ct_cursor(CS_CURSOR_DEALLOC)
ct_send
ct_results
Each step in the process above sends one Client-Library cursor command to the server. After sending each command, the application must handle the results with ct_results. Code your application to handle the results of a cursor command with a standard results loop, as discussed in “Structure of the basic loop”.
