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 arrows indicate that ACTION is set to TDS-GET and the application is retrieving information from the client. The backward arrows indicate that ACTION is set to TDS-SET and 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 CURSOR-COMMAND field is TDS-CURSOR-INFO with TDS-CURSOR-ASKSTATUS option. If the client request is ct_cursor (CS-CURSOR-ROWS), then CURSOR-COMMAND field is TDS-CURSOR-INFO 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-INT, 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.
