CS_CUR_STATUS is a CS_INT-sized quantity that reflects a cursor’s current status.
The status may be either CS_CURSTAT_NONE to indicate no cursor exists for the command structure or a status value with bits set to indicate the status.
If CS_CURSTATUS is not CS_CURSTAT_NONE, the application determines the cursor status by applying the bitmask values listed in the table below. For example, to see if a cursor is updatable, apply the following test:
if ((cur_status & CS_CURSTAT_UPDATABLE)
== CS_CURSTAT_UPDATABLE)
The following table lists the symbolic bitmask values for testing a CS_CUR_STATUS value:
Bitmask value |
Tests for |
|---|---|
CS_CURSTAT_CLOSED |
A closed cursor exists in the command space. An application can open or deallocate a closed cursor. |
CS_CURSTAT_DECLARED |
A cursor is currently declared in this command space. An application can open or deallocate a declared cursor. |
CS_CURSTAT_ROWCOUNT |
The application has sent a cursor-rows command to the server, but the cursor has not been opened yet. |
CS_CURSTAT_OPEN |
An open cursor is open in the command space. An application can close an open cursor. |
CS_CURSTAT_RDONLY |
The cursor is read-only and cannot be used to perform updates. |
CS_CURSTAT_UPDATABLE |
The cursor can be used to perform updates. |
The cursor status is reported by the server. An application must send a ct_cursor command and begin processing the results before it will see a change to the CS_CUR_STATUS property value. Cursor status is guaranteed to be accurate:
After ct_results returns CS_SUCCEED with a *result_type parameter of CS_CMD_SUCCEED, CS_CMD_FAIL, or CS_CURSOR_RESULT
After ct_cancel(CS_CANCEL_ALL) returns CS_SUCCEED
After any Client-Library or CS-Library routine returns CS_CANCELED
Calling ct_cancel may cause a connection’s cursors to enter an undefined state. An application uses the cursor status property to determine how a cancel operation has affected a cursor.
CS_CUR_STATUS is a command structure property and cannot be retrieved at the connection or context levels.
Cursor properties are useful to gateway applications that send cursor information to clients.
For an example fragment that retrieves this property and checks the cursor status, see Example for Cursor Status on page 320.
