The Server Option provides three new functions: TDINFTXT, TDGETTXT, and TDSNDTXT. These functions can be invoked from within a Server Option application written in COBOL or PL/1. The TDINFTXT, TDGETTXT, and TDSNDTXT functions are described in the following sections using COBOL syntax.
Sets or gets a description of text or image data.
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 ITEM-NUMBER PIC S9(9) USAGE COMP SYNC. 01 CS-IODESC FROM SYGWCOB CALL 'TDINFTXT' USING TDPROC, RETCODE, ACTION, ITEM-NUMBER, CS-IODESC.
TDPROC
(I) Handle for the client/server connection. The value here must be the same value specified in the associated TDACCEPT function call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.
RETCODE
(O) Variable to which the result of function execution is returned. The value of this variable is one of the codes listed below under “Returns.”
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 (1) |
The Server Option updates the CS_IODESC structure with the total length of the text or image data to be read from the client. Typically, this is followed by a call to the TDGETTXT function. The Server Option application must set the DATATYPE field in the CS-IODESC structure to TDSTEXT or TDSIMAGE before invoking TDGETTXT. |
TDS_SET (2) |
The Server Option sets internal Server-Library structures to describe a text or image data object. The TDINFTXT call updates a text or image column with the information contained in CS-IODESC. The Server Option application must describe the column using TDESCRIB before TDINFTXT is invoked. |
ITEM-NUMBER
(I) The column number of the column being described. The first column in a row is column 1. This parameter is ignored when ACTION is TDS_GET.
CS-IODESC
(I) A pointer to the CS-IODESC for the application.
TDINFTXT is used to describe text or image columns for sending a result row or retrieving a parameter.
If ACTION is TDS_GET, TDINFTXT must be called prior to the first or only call to TDGETTXT for a row.
If ACTION is TDS_SET, TDINFTXT must be called for each text or image datatype column in a row before TDSNDTXT or TDSNDROW is called.
Text and image data is transferred to the client using either TDSNDTXT or TDSNDROW.
The RETCODE argument can contain any of the following values:
TDS_OK (0)
TDS_INVALID_PARAMETER (-4)
TDS_INVALID_DATA_TYPE (-171)
TDS_ILLEGAL_REQUEST (-5)
TDS_INVALID_LENGTH (-173)
TDS_RESULTS_COMPLETE (500)
TDS_WRONG_STATE (-6)
TDS_CONNECTION_FAILED (-4998)
TDS_CONNECTION_TERMINATED (-4997)
Related functions:
TDSNDTXT
TDGETTXT
Sends a subsequent part of the text or image data stream to the client.
01 TDPROC PIC S9(9) USAGE COMP SYNC. 01 RETCODE PIC S9(9) USAGE COMP SYNC. 01 HOST-VARIABLE-NAME PIC X(n). 01 BUFLEN PIC S9(9) USAGE COMP SYNC. CALL ‘TDSNDTXT’ USING TDPROC, RETCODE, HOST-VARIABLE-NAME, BUFLEN.
TDPROC
(I) Handle for the client/server connection. The value here must be the same value specified in the associated TDACCEPT function call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.
RETCODE
(O) Variable to which the result of function execution is returned. The value of this variable is one of the codes listed below under “Returns.”
HOST-VARIABLE-NAME
(I) Application program variable that contains data for this column.
BUFLEN
(I) The size in bytes of the buffer containing the data.
TDSNDTXT is used when sending a single column of text or image data to the client.
The Server Option application must always call TDINFTXT prior to the first call to TDSNDTXT for the data stream, in order to set the total length of the data to be sent. The application then calls TDSNDTXT to send a part of the data. TDSNDTXT is called as many times as there are sections of data in the data stream.
The item being sent to the client must have previously been described using TDESCRIB.
A Server Option application can also write text and image data to a client using TDSNDROW. TDSNDTXT allows the application to send the data in sections, whereas the standard TDSNDROW method requires that all the data in the column be sent in one piece.
A column sent with TDSNDTXT must be of type text or image.
The Server Option treats text and image data streams identically except for character set conversion, which is only performed on text data.
The RETCODE argument can contain any of the following values:
TDS_OK (0)
TDS_ILLEGAL_REQUEST (-5)
TDS_INVALID_VAR_ADDRESS (-175)
TDS_CANCEL_RECEIVED (-12)
TDS_WRONG_STATE (-6)
TDS_INVALID_LENGTH (-173)
TDS_CONNECTION_TERMINATED (-4997)
Related functions:
TDGETTXT
TDINFTXT
Reads a subsequent part of a text or image datastream from the client.
01 TDPROC PIC S9(9) USAGE COMP SYNC. 01 RETCODE PIC S9(9) USAGE COMP SYNC. 01 HOST-VARIABLE-NAME PIC X(n). 01 BUFLEN PIC S9(9) USAGE COMP SYNC. 01 OUTLEN PIC S9(9) USAGE COMP SYNC. CALL ’TDSNDTXT’ USING TDPROC, RETCODE, HOST-VARIABLE NAME, BUFLEN.
TDPROC
(I) Handle for the client/server connection. The value here must be the same value specified in the associated TDACCEPT function call. The TDPROC handle corresponds to the connection and command handles in Open Client Client-Library.
RETCODE
(O) Variable to which the result of function execution is returned. The value of this variable is one of the codes listed below under “Returns.”
HOST-VARIABLE-NAME
(I) Application program variable to receive a subsequent part of the incoming text or image client data.
BUFLEN
(I) The size in bytes of the buffer containing the data.
OUTLEN
(O) The length in bytes of the data received.
TDGETTXT is used to read bulk data from the client. The bulk data can be of type text or image.
TDGETTXT must be called until all of the bulk data has been read from a client. The Server Option application must keep track of the data that remains to be read.
A column read with TDGETTXT must be of type text or image.
A Server Option application must call TDINFTXT prior to the first call to TDGETTXT for the data stream. The application then calls TDGETTXT to retrieve a section of data. TDGETTXT is called as many times as are necessary to read in the whole stream.
The Server Option application must set the CS_IODESC DATATYPE field to TDSTEXT or TDSIMAGE before invoking the TDINFTXT and TDGETTXT functions. In the case in which DATATYPE is set to TDSTEXT, the Server Option translates the character set for the client data before sending the data to the Server Option application.
The RETCODE argument can contain any of the following values:
TDS_OK (0)
TDS_INVALID_VAR_ADDRESS (-175)
TDS_INVALID_LENGTH (-173)
TDS_ILLEGAL_REQUEST (-5)
TDS_CONNECTION_FAILED (-4998)
TDS_CONNECTION_TERMINATED (-4997)
Related functions:
TDSNDTXT
TDINFTXT
| Copyright © 2005. Sybase Inc. All rights reserved. |
|
|
