Retrieves or sets information about a cursor.
COPY SYGWCOB. 01 TDPROC PIC S9(9) USAGE COMP SYNC. 01 RETCODE PIC S9(9) USAGE COMP SYNC. 01 ACTION PIC S9(9) USAGE COMP SYNC. 01 CURSOR-DESC FROM SYGWCOB. CALL ‘TDCURPRO’ USING TDPROC, RETCODE, ACTION, CURSOR-DESC.
The CURSOR-DESC structure is defined in SYGWCOB as follows:
CURSOR-ID PIC S9(9) USAGE COMP SYNC. NUMBER-OF-UPDATE-COLUMNS PIC S9(9) USAGE COMP SYNC. FETCH-COUNT PIC S9(9) USAGE COMP SYNC. CURSOR-STATUS PIC S9(9) USAGE COMP SYNC. CURSOR-COMMAND PIC S9(9) USAGE COMP SYNC. COMMAND-OPTIONS PIC S9(9) USAGE COMP SYNC FETCH-TYPE PIC S9(9) USAGE COMP SYNC. ROW-OFFSET PIC S9(9) USAGE COMP SYNC. CURSOR-NAME-LENGTH PIC S9(9) USAGE COMP SYNC. CURSOR-NAME PIC X(30). TABLE-NAME-LENGTH PIC S9(9) USAGE COMP-SYNC. TABLE-NAME PIC X(30).
(I) Handle for this client/server connection. This must be the same value specified in the associated TDACCEPT call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.
(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-5.
(I) Action to be taken by this call. ACTION is an integer variable that indicates the purpose of this call.
Assign ACTION one of the following symbolic values:
TDS-GET (33) |
Retrieves cursor information. |
TDS-SET (34) |
Specifies cursor information. |
(I/O) A CURSOR-DESC structure containing information in the following fields:
This field |
Contains this information |
|---|---|
CURSOR-ID |
The cursor identifier. |
NUMBER-OF-UPDATE- COLUMNS |
The number of columns in a cursor update clause. |
FETCH-COUNT |
The current row fetch count for this cursor; that is, the number of rows that are sent to the client in response to a TDS-CURSOR-FETCH command. |
CURSOR-STATUS |
The status of the current cursor. |
CURSOR-COMMAND |
The current cursor command type. |
COMMAND-OPTIONS |
Any options associated with the cursor command. |
FETCH-TYPE |
The type of fetch requested by a client. |
ROW-OFFSET |
The row position for TDS-ABSOLUTE or TDS-RELATIVE fetches. |
CURSOR-NAME-LENGTH |
The length of the cursor name in CURSOR-NAME. |
CURSOR-NAME |
The name of the current cursor. |
TABLE-NAME-LENGTH |
The length of the tablename in TABLE-NAME. |
TABLE-NAME |
The table name associated with a cursor update or delete command. |
The RETCODE argument can contain any of the return values listed in Table 3-5.
Return value |
Meaning |
|---|---|
TDS-OK (0) |
Function completed successfully. |
TDS-BUFFLEN-GREATER-TYPE (-191) |
TDYNAMIC: The size of the buffer is greater than the dynamic SQL-type field being retrieved. |
TDS-BUFFLEN-LESS-TYPE (-192) |
TDYNAMIC: The size of the buffer is too small to return a dynamic SQL-type field. |
TDS-CANCEL-RECEIVED (-12) |
Operation canceled. The remote partner issued a cancel. The current operation failed. |
TDS-CMD-NOT-GET-SET (-190) |
The value of the ACTION argument is invalid. It should be either TDS-GET or TDS-SET. |
TDS-CONNECTION-FAILED (-4998) |
Connection abended. The client/server connection abnormally ended (for example, the LU 6.2 session crashed or the remote transaction abended). |
TDS-CONNECTION-TERMINATED (-4997) |
Connection closed. The remote partner closed (deallocated) the client/server connection. |
TDS-CURSOR-ALREADY-OPEN (-74) |
Cursor already open. You cannot open the same cursor more than once. |
TDS-CURSOR-NOT-CLOSED (-73) |
Cursor is still active (deallocate without close first). |
TDS-CURSOR-NOT-DECLARED (-70) |
A cursor must be declared before it can be opened. |
TDS-CURSOR-NOT-OPEN (-72) |
Cursor not open. A cursor must be open before a fetch, close, delete, or update. |
TDS-ENTRY-NOT-FOUND (-8) |
The specified column number, transaction number, or parameter does not exist. |
TDS-INVALID-CURCLOSOPTION (-182) |
A closed cursor command specified an invalid option. The Gateway-Library transaction received a closed cursor command, but the value of the OPTION field of the CURSOR-DESC structure is invalid. Valid options are TDS-CUR-UNUSED and TDS-CUR-DEALLOC. |
TDS-INVALID-CURDECLOPTION (-183) |
A declare cursor command has an invalid option specified. The Gateway-Library transaction received a declare cursor command, but the value of the OPTION field of the CURSOR-DESC structure is invalid. Valid options are TDS-CUR-UNUSED and TDS-CUR-DEALLOC. |
TDS-INVALID-CURDECLSTAT (-184) |
Illegal cursor declare option. |
TDS-INVALID-CURINFCMD (-195) |
Illegal cursor information command. |
TDS-INVALID-CURINFSTAT (-185) |
Illegal cursor information status. |
TDS-INVALID-CUROPENSTAT (-187) |
Illegal cursor open status. |
TDS-INVALID-CURSOR-COMMAND (-194) |
The cursor command is not declare, open, fetch, delete, update, or close. |
TDS-INVALID-CURSOR-FSM (-78) |
Invalid cursor state. |
TDS-INVALID-CURUPDSTAT (-186) |
Illegal cursor update status. |
TDS-INVALID-OP-TYPE (-193) |
Invalid dynamic SQL operation. |
TDS-INVALID-TDPROC (-18) |
Error in specifying a value for the TDPROC argument. |
TDS-NO-CURRENT-CURSOR (-200) |
No cursor is associated with the current transaction. |
TDS-WRONG-STATE (-6) |
This function cannot be used in the current communication state. For example, your program tried to send a reply before it read in all of the client parameters. The application was still in RECEIVE state and could not send. The operation failed. |
An Open ServerConnect application uses this function to exchange active cursor information with a client.
A transaction first calls TDCURPRO, with an ACTION of TDS-GET to retrieve the client cursor command and other information about the cursor (for example, the requested fetch count). The CURSOR-DESC structure provides this information.
After processing the client command, the transaction calls TDCURPRO with an ACTION of TDS-SET to return acknowledgment and/or updated cursor information to the client.
Each type of cursor command requires a distinct response from the Open ServerConnect application. Cursor commands and their responses are discussed under “Types of cursor commands”.
An application can also read in parameters or send back result rows, depending on the circumstances.
An application can call TDCURPRO for any cursor by specifying which cursor in the CURSOR-ID field of the CURSOR-DESC structure. Cursors need not be called in any particular order.
The CURSOR-COMMAND field in the CURSOR-DESC structure indicates the command to be processed.
When a client declares a new cursor (CURSOR-COMMAND is TDS-CURSOR-DECLARE), the client provides a cursor name, but not a cursor ID. It is the responsibility of the Open ServerConnect application to assign a unique cursor ID to the new cursor and return that ID to the client.
To do this,
Specify TDS-SET for the ACTION argument.
Specify the new cursor ID in the CURSOR-ID field in the CURSOR-DESC structure.
Return this information to the client.
Both the client and the Open ServerConnect applications must subsequently
refer to this cursor by its ID rather than its name.
The application must acknowledge all cursor commands except fetch, update, and delete by sending back a cursor information command.
To do this, specify TDS-SET in the ACTION argument.
This is the very first piece of information the application sends back after receiving a cursor command. The application sets the cursor ID. This information comes back on every command.
For example, after receiving a close cursor request, Open ServerConnect sets CURSOR-COMMAND to TDS-CURSOR-INFO and CURSOR-STATUS to TDS-CURSTAT-CLOSED.
This is done by Open ServerConnect, not by the application.
Multiple cursor commands per transaction invocation are not allowed. To process multiple commands, use the long-running transaction, accepting each new command request with TDGETREQ.
Related functions
