srv_cursor_props

Description

Retrieve or set information about the current cursor.

Syntax

CS_RETCODE srv_cursor_props(spp, cmd, cdp)

SRV_PROC            *spp;
CS_INT                   cmd;
SRV_CURDESC    *cdp;

Parameters

spp: A pointer to an internal thread control structure.

cmd

Indicates whether srv_cursor_props sends cursor information to the client or retrieves cursor information from the client. The following table describes the legal values for cmd:

**Table 3-27: Values for cmd (srv_cursor_props)**
Value	Description
CS_SET	srv_cursor_props sends information about the current cursor to the client.
CS_GET	srv_cursor_props retrieves information about the current cursor command from the client.

cdp: A pointer to a SRV_CURDESC structure. When the application is setting cursor information, the SRV_CURDESC structure describes the current cursor. When the application is retrieving information, Open Server updates the SRV_CURDESC structure with information about the current cursor. Various fields are set or filled in at various times, depending on the current cursor command. For an explanation of each field in cdp and how and when they are filled in, see “SRV_CURDESC structure”.

Returns

**Table 3-28: Return values (srv_cursor_props)**
Returns	To indicate
CS_SUCCEED	The routine completed successfully.
CS_FAIL	The routine failed.

Examples

Example 1

#include          <ospublic.h>

/*

 ** Local Prototype.

*/

extern CS_RETCODE     ex_srv_cursor_props PROTOTYPE((

CS_VOID               *spp

));

/*

 ** EX_SRV_CURSOR_PROPS

**

**     Example routine to retrieve information on the current

 **     cursor.

** Arguments:

**  spp  Apointer to an internal control structure.

**

** Returns:

**

**  CS_SUCCEED     Cursor information was retrieved successfully.

**  CS_FAIL        An error was detected.

*/

CS_RETCODE         ex_srv_cursor_props(spp)

SRV_PROC           *spp;

     SRV_CURDESC   curdesc;

     if(srv_cursor_props(spp, CS_GET, &curdesc) == CS_FAIL)

          return(CS_FAIL);

     return(CS_SUCCEED);

Usage

An Open Server application uses srv_cursor_props to exchange active cursor information with the client.
The client always initiates this exchange by issuing a cursor command. The client, therefore, specifies the current cursor.
An application can only call srv_cursor_props from inside a SRV_CURSOR event handler.
Open Server generates a SRV_CURSOR event in response to each cursor command received from a client. An application’s SRV_CURSOR event handler can then call srv_cursor_props with cmd set to CS_GET to determine the current cursor and the type of cursor command received. It can then decide how to respond. For a description of valid cursor command types and legal responses, see “Cursors”.
Each cursor command provokes a distinct response from an Open Server application. The application pulls information from the SRV_CURDESC structure (the requested fetch count, for example), makes decisions based on that data, and then sets information in the structure and sends it back to the client using srv_cursor_props. An application can also read in parameters, or send back result rows and parameters, depending on the circumstances.
The SRV_CURSOR event handler must acknowledge all cursor commands except fetch, update, and delete by sending back a cursor information command. The handler sets the curcmd field in the SRV_CURDESC structure to CS_CURSOR_INFO and then calls srv_cursor_props with cmd set to CS_SET. This is the very first piece of information the handler sends back.
In response to a CURSOR_DECLARE command, an Open Server application chooses a cursor ID to uniquely identify the current cursor. The application then sends the cursor ID back to the client by calling srv_cursor_props with cmd set to CS_SET. The client and Open Server application subsequently refer to the current cursor by its ID rather than its name.