This section describes how a SRV_CURSOR event handler should respond to specific types of cursor requests.
Prior to calling srv_cursor_props with cmd set to CS_SET, an Open Server application must always set the curid field, and any other pertinent fields, in the SRV_CURDESC structure.
Table 2-15 summarizes the valid exchange of cursor requests and responses between a client and an Open Server application. The forward arrow (→) indicates that cmd is set to CS_GET—the Open Server application retrieves information from the client. The backward arrow (←) indicates that cmd is set to CS_SET—the Open Server application sends information to the client.
Client action |
Open Server application response |
|---|---|
Declares a cursor (curcmd field of SRV_CURDESC contains CS_CURSOR_DECLARE) |
− >Retrieve curcmd value from SRV_CURDESC (srv_cursor_props) − >Retrieve number of cursor parameters, if any (srv_numparams) − >Retrieve format of cursor parameters, if any (srv_descfmt with type argument set to SRV_CURDATA) − >Retrieve update column information, if any (srv_descfmt with type argument set to SRV_UPCOLDATA) − >Retrieve actual text of cursor command (srv_langlen and srv_langcpy) < − Set cursor ID. Set curcmd field to CS_CURSOR_INFO and curid field to unique cursor ID (srv_cursor_props) < − Send a DONE packet. (srv_senddone with status argument set to SRV_DONE_FINAL) |
Requests the status of the current cursor or sends a fetch count (curcmd field of SRV_CURDESC contains CS_CURSOR_INFO) |
− >Retrieve curcmd and curid cmdoptions values from SRV_CURDESC structure (srv_cursor_props) < − Send number of rows to be returned per fetch, if client set cmdoptions field to SRV_CUR_SETROWS (srv_cursor_props with curcmd set to CS_CURSOR_INFO) < − Send status of all available cursors, if client set cmdoptions field to SRV_CUR_ASKSTATUS. Set curcmd field to CS_CURSOR_INFO and curid field to cursor ID (srv_cursor_props once for each active—declared, opened or closed—cursor) < − Send a DONE packet (srv_senddone with status argument set to SRV_DONE_FINAL) |
Opens a cursor (curcmd field of SRV_CURDESC contains CS_CURSOR_OPEN) |
- > Retrieve curcmd and curid values from SRV_CURDESC structure (srv_cursor_props) − > Retrieve number of cursor parameters, if any (srv_numparams) − > Retrieve format of cursor parameters and actual parameters, if any (srv_descfmt, srv_bind, srv_xferdata with type argument set to SRV_CURDATA) < − Send cursor status. Set curid to current cursor ID and curcmd to CS_CURSOR_INFO (srv_cursor_props) < − Describe result row formats (srv_descfmt with type argument set to SRV_ROWDATA) < − Send a DONE packet (srv_senddone with status argument set to SRV_DONE_FINAL) |
Fetches rows (curcmd field of SRV_CURDESC contains CS_CURSOR_FETCH) |
− > Retrieve curcmd and curid values from SRV_CURDESC structure (srv_cursor_props) < − Send result rows, fetchcnt times (srv_bind, srv_xferdata with type argument set to SRV_ROWDATA) < − Send a DONE packet (srv_senddone with status argument set to SRV_DONE_FINAL) |
Issues cursor update command (curcmd field of SRV_CURDESC contains CS_CURSOR_UPDATE) or Issues cursor delete command (curcmd field of SRV_CURDESC contains CS_CURSOR_DELETE) |
− > Retrieve curcmd and curid values from SRV_CURDESC structure (srv_cursor_props) − > Retrieve key columns for current row (srv_descfmt, srv_bind, srv_xferdata with type argument set to SRV_KEYDATA) − > Retrieve number of update values, if curcmd is CS_CURSOR_UPDATE (srv_numparams) Retrieve actual text of update statement, if curcmd is CS_CURSOR_UPDATE (srv_langlen and srv_langcpy) − > Retrieve update values, if curcmd is CS_CURSOR_UPDATE (srv_descfmt, srv_bind, srv_xferdata, with type argument set to SRV_CURDATA) < − Send a DONE packet (srv_senddone with status argument set to SRV_DONE_FINAL) |
Sends a cursor close command (curcmd field of SRV_CURDESC contains CS_CURSOR_CLOSE) |
− > Retrieve curcmd and curid values from SRV_CURDESC structure (srv_cursor_props) < − Send cursor status (srv_cursor_props) < − Send a DONE packet (srv_senddone with status argument set to SRV_DONE_FINAL) |
Note that:
The Open Server application’s response to a cursor command always concludes with a call to srv_senddone with a status argument of “SRV_DONE_FINAL.”
Once the Open Server application issues the first srv_cursor_props command with cmd set to “SET”, any further information the application sends will apply to this cursor until a srv_senddone with a status argument of SRV_DONE_FINAL is issued.
Internally, Open Server replaces the parameter formats received when the client declares a cursor with those received when the client opens a cursor. This procedure is necessary in case the format of the parameter passed in is not exactly the same as that of the parameter declaration. For example, a parameter may be declared as a CS_INT, but the parameter being passed in when the cursor is opened may be of type CS_SMALLINT.
srv_xferdata sends a single row of data, and should be called as many times as the number in the current cursor’s row fetch count, in response to a CS_CURSOR_FETCH command.
