Chapter 3: Functions

TDSNDROW

Description

Sends a row of data back to the requesting client, over the specified connection.

Syntax

COPY SYGWCOB.

01 TDPROC   PIC S9(9)  USAGE COMP SYNC.
01 RETCODE  PIC S9(9)  USAGE COMP SYNC.

CALL 'TDSNDROW' USING TDPROC, RETCODE.

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

Returns

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

**Table 3-41: TDSNDROW return values**
Return value	Meaning
TDS-OK (0)	Function completed successfully.
TDS-CANCEL-RECEIVED (-12)	Operation canceled. The remote partner issued a cancel. The current operation failed.
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-DATE-CONVERSION-ERROR (-23)	Error in conversion of datetime data. This can be a result of trying to convert short datetime (TDSDATETIME4) for a client using an early TDS version. TDS versions earlier than 4.2 do not support the short datetime datatype.
TDS-DECIMAL-CONVERSION-ERROR (-24)	Error in conversion of packed decimal data.
TDS-FLOAT-CONVERSION-ERROR (-21)	Error in conversion of float values.
TDS-ILLEGAL-REQUEST (-5)	Illegal function. The operation failed. This code can indicate that a client application is trying to use a Gateway-Library function that is not supported for clients (for example, TDSNDROW).
TDS-INVALID-LENGTH (-173)	The length specified in the preceding TDESCRIBE is wrong.
TDS-INVALID-PARAMETER (-4)	Invalid parameter value. The value assigned to one or more of the arguments supplied in the call is not valid. The operation failed.
TDS-INVALID-TDPROC (-18)	Error in specifying a value for the TDPROC argument.
TDS-MONEY-CONVERSION-ERROR (-22)	Error in conversion of TDSMONEY-type data. This can be a result of trying to convert to short money (TDSMONEY4) for a client using an early TDS version. TDS versions earlier than 4.2 do not support the short money datatype.
TDS-TRUNCATION-ERROR (-20)	Error occurred in truncation of data value.
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.

Examples

Example 1

The following code fragment illustrates a typical use of TDSNDROW in a paragraph that converts packed decimal data to the client money datatype before sending the row to the client. This example is taken from the sample program, SYCCSAR2, in Appendix B, “Sample RPC Application for CICS.”

 *-----------------------------------------------------------------
  FETCH-AND-SEND-ROWS.
 *-----------------------------------------------------------------
      EXEC SQL FETCH ECURSOR INTO :EMPLOYEE-FIELDS END-EXEC.
 
      IF SQLCODE = 0 THEN
 
 *        Convert from DB2 decimal (TDSDECIMAL) to dblib MONEY.
 
          MOVE LENGTH OF EMPLOYEE-SAL     TO WRKLEN1
          MOVE LENGTH OF WRK-EMPLOYEE-SAL TO WRKLEN2
 
          CALL 'TDCONVRT' USING GWL-PROC, GWL-RC,
                                GWL-CONVRT-SCALE, TDSDECIMAL,
                                WRKLEN1, EMPLOYEE-SAL, TDSMONEY,
                                WRKLEN2, WRK-EMPLOYEE-SAL
 
 *        send a row to the client
 
          CALL 'TDSNDROW' USING GWL-PROC, GWL-RC
          ADD 1 TO PARM-RETURN-ROWS
 
          IF GWL-RC = TDS-CANCEL-RECEIVED THEN
             MOVE 'Y' TO ALL-DONE-SW
          END-IF
 
      ELSE IF SQLCODE = +100 THEN
          MOVE 'Y' TO ALL-DONE-SW
 
      ELSE
          MOVE 'Y' TO ALL-DONE-SW
          PERFORM FETCH-ERROR
      END-IF.

Usage

A server application uses this function to send a row of data to the requesting client over the connection specified in TDPROC. Each TDSNDROW sends a single row, so the application must issue a TDSNDROW call for each row to be sent.

TDSNDROW sends the column name and format before it sends the column data.

If your IMS TM transaction is conversational (CONV), you must insert the scratch pad area at the beginning of the IO/PCB before sending the results with TDSNDROW.
A server application cannot send any data rows to the client after it issues TDSNDMSG or TDSNDDON, unless the TDSNDDON status is TDS-DONE-CONTINUE.
Before a row of data can be sent to a client, every column of the row must be defined in a TDESCRIB call. If your application calls TDSNDROW before all the columns in the row are described with TDESCRIB, this function returns TDS-WRONG-STATE, and the row is not sent.
If the column datatype is TDSVARYCHAR, TDSVARYBIN, or TDSVARYGRAPHIC, the column length is determined each time a row is sent by the value of the “LL” specification at the beginning of the column structure.

Datatype conversions

Table 3-42 shows the conversions that TDSNDROW performs.

**Table 3-42: Datatype conversions performed by TDSNDROW**
Source datatype: Gateway-Library	Result datatype: Open Client	Notes
TDSCHAR TDSCHAR TDSVARYCHAR TDSVARYCHAR TDSVARYCHAR	TDSVARYCHAR TDSMONEY TDSCHAR TDSLONGVARCHAR TDSMONEY	Performs EBCDIC and ASCII conversion. For Japanese character sets, does mainframe to workstation conversion. Pads TDSCHAR fields with blanks.
TDSFLT8 TDSFLT8 TDSFLT8	TDSFLT4 TDSMONEY TDSMONEY4	Truncates low order digits.
TDSFLT4 TDSFLT4 TDSFLT4	TDSFLT8 TDSMONEY TDSMONEY4
TDSCHAR TDSVARYCHAR	TDSMONEY TDSMONEY
TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL TDS-PACKED-DECIMAL	TDSCHAR TDSVARYCHAR TDSMONEY TDSFLT4 TDSFLT8	When converting packed decimal to character values, change the length to allow for unpacking, leading or trailing zeros, the sign and the decimal point.
TDS-PACKED-DECIMAL TDSCHAR	TDSNUMERIC TDSNUMERIC	Use TDSETBCD after TDESCRIB to set precision and scale for numeric or Sybase decimal columns.
TDS-PACKED-DECIMAL TDSCHAR	TDS-SYBASE-DECIMAL TDS-SYBASE-DECIMAL	Use TDSETBCD after TDESCRIB to set precision and scale for numeric or Sybase decimal columns.
TDSGRAPHIC TDSGRAPHIC TDSVARGRAPHIC TDSVARGRAPHIC	TDSCHAR TDSVARYCHAR TDSCHAR TDSVARYCHAR	Performed by Japanese Conversion Module. Pads TDSCHAR fields with blanks.
TDSDATETIME TDSDATETIME4	TDSCHAR TDSCHAR

Your application must be in SEND state for this function to execute successfully. If it is not in SEND state, TDSNDROW returns TDS-WRONG-STATE. Calling TDRESULT puts your application in SEND state.
If the RETCODE argument contains the value, TDS-CANCEL-RECEIVED, your application should immediately stop sending rows and issue TDSNDDON and TDFREE. It is a good idea to check the return code after each row is sent.

For Japanese users

If the JCM is used, TDSNDROW converts the data in a column from the mainframe character set to the workstation character set before sending, if necessary.