This section contains information on how a TDS_CURSOR_EVENT handler should respond to specific types of cursor requests.
On each cursor declare request, the Open ServerConnect application must set a unique cursor identifier before TDCURPRO, with ACTION set to TDS_SET. Open ServerConnect sets CURSOR_STATUS and CURSOR_COMMAND in the CURSOR_DESC structure.
Table 2-8 summarizes the valid exchange of cursor requests and responses between a client and an Open ServerConnect application. The forward arrow indicates that ACTION is set to TDS_GET, which means the application is retrieving information from the client. The backward arrow indicates that ACTION is set to TDS_SET, which means the application is sending information to the client.
Client action |
Open ServerConnect application response |
|---|---|
Declares a cursor. (CURSOR_COMMAND field of CURSOR_DESC contains TDS_CURSOR_DECLARE. |
→ Retrieve CURSOR_COMMAND value from CURSOR_DESC. (TDCURPRO) → Retrieve number of cursor parameters, if any. (TDNUMPRM) → Retrieve format of cursor parameters, if any. (TDINFPRM) → Retrieve actual text of cursor command. (TDRCVSQL) ← Set cursor ID. Set CURSOR_ID field to unique cursor ID. (TDCURPRO) ← Send a DONE packet. (TDSNDDON with STATUS argument set to TDS_DONE_FINAL. |
Requests the status of the current cursor or sends a fetch count. (CURSOR_COMMAND field of CURSOR_DESC contains TDS_CURSOR_INFO. |
→ Retrieve CURSOR_COMMAND, CURSOR_ID, and COMMAND_OPTIONS values from CURSOR_DESC structure. (TDCURPRO) ← Send number of rows to be returned per fetch, if client set COMMAND_OPTIONS field to TDS_CURSOR_SETROWS. (TDCURPRO) ← Send status of all available cursors, if client set COMMAND_OPTIONS field to TDS_CURSOR_ASKSTATUS. Set CURSOR_ID field to cursor ID. (TDCURPRO once for each active declared, opened or closed cursor.) ← Send a DONE packet. (TDSNDDON with STATUS argument set to TDS_DONE_FINAL.) Note: If the client request is ct_cmd_props with cursor options, then the CURSOR_COMMAND field is TDS_CURSOR_INFO with TDS_CURSOR_ASKSTATUS option. If the client request is ct_cursor (CS_CURSOR_ROWS), then the CURSOR_COMMAND field is TDS_CURSOR_INFOR with TDS_CURSOR_SETROWS option. |
Opens a cursor. (CURSOR_COMMAND field of CURSOR_DESC contains TDS_CURSOR_OPEN. |
→ Retrieve CURSOR_COMMAND and CURSOR_ID values from CURSOR_DESC structure. (TDCURPRO) → Retrieve number of cursor parameters, if any. (TDNUMPRM) → Retrieve format of cursor parameters and actual parameters, if any. (TDINFPRM, TDRCVPRM) ← Send cursor status. Set CURSOR_ID to current cursor ID. (TDCURPRO) ← Describe result row formats. (TDESCRIB with TYPE argument set to TDS_ROWDATA) ← Send a DONE packet. (TDSNDDON with STATUS argument set to TDS_DONE_FINAL. |
Fetches rows. (CURSOR_COMMAND field of CURSOR_DESC contains TDS_CURSOR_FETCH. |
→ Retrieve CURSOR_COMMAND and CURSOR_ID values from CURSOR_DESC structure. (TDCURPRO) ← Send result rows, FETCH_COUNT times. (TDSNDROW) ← Send a DONE packet. (TDSNDDON with STATUS argument set to TDS_DONE_FINAL. |
Sends a cursor close command. (CURSOR_COMMAND field of CURSOR_DESC contains TDS_CURSOR_CLOSE. |
→ Retrieve CURSOR_COMMAND and CURSOR_ID values from CURSOR_DESC structure. (TDCURPRO) ← Send cursor status. Open ServerConnect sets cursor status, not the application. (TDCURPRO) ← Send a DONE packet. (TDSNDDON with STATUS argument set to TDS_DONE_FINAL. |
Updates a cursor. CURSOR_COMMAND field of CURSOR_DESC contains TDS_CURSOR_UPDATE. |
→ Retrieve CURSOR_COMMAND and CURSOR_ID values from CURSOR_DESC structure. (TDCURPRO) → Retrieve actual text of cursor command. (TDRCVSQL) ← Send a DONE packet. (TDSNDDON with STATUS argument set to TDS_DONE_FINAL. |
Deletes a cursor. CURSOR_COMMAND field of CURSOR_DESC contains TDS_CURSOR_DELETE. |
→ Retrieve CURSOR_COMMAND and CURSOR_ID values from CURSOR_DESC structure. (TDCURPRO) ← Send a DONE packet. (TDSNDDON with STATUS argument set to TDS_DONE_FINAL) |
The Open ServerConnect application response to a cursor command always concludes with a call to TDSNDDON with a STATUS argument of TDS_DONE_FINAL.
After the Open ServerConnect application issues the first TDCURPRO command with ACTION set to TDS_SET, any further information the application sends applies to this cursor until a TDSNDDON with a STATUS argument of TDS_DONE_FINAL is issued.
Internally, Open ServerConnect replaces the parameter formats received when the client declares a cursor with those received when the client opens a cursor. This is necessary if the format of the parameter passed is not exactly the same as that of the parameter declaration. For example, a parameter may be declared as a TDS_INIT, but the parameter being passed when the cursor is opened may be of type TDS_SMALLINT.
In response to a TDS_CURSOR_FETCH command, TDSNDROW sends a single row of data, and should be called as many times as the number in the current cursor’s row fetch count.
