Retrieves or sets information about a cursor.
%INCLUDE SYGWPLI; 01 TDPROC FIXED BIN (31), 01 RETCODE FIXED BIN (31), 01 ACTION FIXED BIN (31), 01 CURSOR_DESC from SYGWPLI;
CALL TDCURPRO (TDPROC, RETCODE, ACTION,
CURSOR_DESC);
The CURSOR_DESC structure is defined in SYGWPLI as follows:
CURSOR_ID FIXED BIN (31), NUMBER_OF_UPDATE_COLUMNS FIXED BIN (31), FETCH_COUNT FIXED BIN (31), CURSOR_STATUS FIXED BIN (31), CURSOR_COMMAND FIXED BIN (31), COMMAND_OPTIONS FIXED BIN (31), FETCH_TYPE FIXED BIN (31), ROW_OFFSET FIXED BIN (31), CURSOR_NAME_LENGTH FIXED BIN (31), CURSOR_NAME CHAR (n), TABLE_NAME_LENGTH FIXED BIN (31), TABLE_NAME CHAR(n);
(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 TDCURPRO 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 the responses are discussed in “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 the 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 by 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.
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
