TDCURPRO

Description

Retrieves or sets information about a cursor.

Syntax

%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);

Parameters

TDPROC

(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.

RETCODE

(O) Variable where the result of function execution is returned. Its value is one of the codes listed in Table 3-5.

ACTION

(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.

CURSOR_DESC

(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.

Returns

The RETCODE argument can contain any of the return values listed in Table 3-5.

Usage

TDCURPRO

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:

  1. Specify TDS_SET for the ACTION argument.

  2. Specify the new cursor ID in the CURSOR_ID field in the CURSOR_DESC structure.

  3. 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.

See also

Related functions

• TDACCEPT

• TDGETREQ

Copyright © 2005. Sybase Inc. All rights reserved.

View this book as PDF