After a Client-Library cursor is declared, an application can call ct_cursor to specify a cursor-rows setting for the cursor. The value of the cursor-rows setting defines the number of rows that the server returns to Client-Library per internal fetch request, not the number of rows returned to an application per ct_fetch call. An internal fetch request is made when more rows are needed from the server to satisfy ct_fetch requests.
By default, the cursor-rows setting is 1. If the application does not send a cursor-rows command that precedes the cursor-open command, the cursor rows setting is 1. For cursors declared with ct_cursor commands, the cursor-rows command can be batched with the cursor-open command.
The cursor-rows settings determines how many rows Client-Library receives from the server in response to each internal Client-Library fetch request. For example, if cursor-rows is set to 5 and the application does not use array binding, Client-Library makes an internal fetch request when an application calls ct_fetch the first time, the sixth time, and so on.
To facilitate a multi-row return from ct_scroll_fetch, you must use a cursor-row setting greater than 1. For maximum efficiency, you must also use array binding. Your array bind count should be equal to the CS_CURSOR_ROWS value.
Array binding is required for ct_scroll_fetch if the CS_CURSOR_ROWS setting
is greater than 1. Array binding can be used with both ct_fetch and ct_scroll_fetch.
If CS_CURSOR_ROWS is set to the default value
of 1, normal program variables may be used with either API call.
If you specify a cursor-rows setting greater than 1, Client-Library buffers also handles additional internal row fetches transparently. When an application calls ct_fetch to fetch a cursor row, Client-Library may read the row directly from the network, send an internal fetch request to the server to get more rows, or retrieve the row from an internal row buffer. Two situations require Client-Library to buffer cursor rows internally:
When the application sends a nested cursor-update or cursor-delete command.
When the application sends a command on a different command structure than the cursor’s.
In these situations, Client-Library must read and buffer any unread rows to clear the connection for writing.
In general, a higher cursor-rows setting can benefit application performance when processing a read-only cursor. A higher cursor-rows setting decreases the number of network round trips required to fetch rows. However, if cursor-rows is set too high and Client-Library must buffer rows, the buffering overhead can outweigh the gains achieved by decreasing the number of round trips.
To minimize the likelihood that Client-Library will need to buffer rows, use array binding with an array size that matches the cursor-rows setting. See the reference page for ct_bind in the Open Client Client-Library/C Reference Manual.
