Cursor status

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)

Table 2-30 lists the symbolic bitmask values for testing a CS_CUR_STATUS value:

**Table 2-30: Cursor status bitmask values**
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.
CS_SCROLL_INSENSITIVE	Declares a scrollable, insensitive cursor.
CS_SCROLL_SEMISENSITIVE	Declares a scrollable, semi sensitive cursor.
CS_SCROLL_CURSOR	Declares a scrollable cursor that is insensitive (default).
CS_NOSCROLL_INSENSITIVE	Declares a cursor insensitive and non-scrollable.

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.