Sends a row of data back to the requesting client, over the specified connection.
% INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31);
CALL TDSNDROW (TDPROC, RETCODE);
(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-41.
The RETCODE argument can contain any of the return values listed in Table 3-41.
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. |
The following code fragment illustrates a typical use of TDSNDROW. This example is taken from the sample program in Appendix B, “Sample RPC Application for CICS.”
/*------------------------------------------------------------------*/
SEND_ROWS:
/*------------------------------------------------------------------*/
DO WHILE(^ ALL_DONE);
CALL FETCH_AND_SEND_ROWS;
END;
/*------------------------------------------------------------------*/
FETCH_AND_SEND_ROWS: PROC;
/*------------------------------------------------------------------*/
EXEC SQL FETCH ECURSOR INTO :EMPLOYEE_FIELDS;
IF SQLCODE = 0 THEN
DO;
/* --------------------------------------------------------*/
/* Convert from DB2 decimal (TDSDECIMAL) to dblib MONEY. */
/* --------------------------------------------------------*/
WRKLEN1 = STG(EMPLOYEE_SAL);
WRKLEN2 = STG(WRK_EMPLOYEE_SAL);
CALL TDCONVRT (GWL_PROC, GWL_RC,
GWL_CONVRT_SCALE,
TDSDECIMAL,
WRKLEN1,
EMPLOYEE_SAL,
TDSMONEY,
WRKLEN2,
WRK_EMPLOYEE_SAL);
/* --------------------------------------------------------*/
/* Do not send trailing blanks of EMPLOYEE_LNM */
/* --------------------------------------------------------*/
WRKLEN1 = LENGTH(EMPLOYEE_LNM);
CTR_COLUMN = 2;
WRK_BLANKS_SS = 1;
LOOP: DO WHILE(WRK_BLANKS_SS <= WRKLEN1);
IF SUBSTR(EMPLOYEE_LNM, WRK_BLANKS_SS, 1) = ' ' THEN DO;
LEAVE LOOP;
END;
WRK_BLANKS_SS = WRK_BLANKS_SS + 1;
END LOOP;
IF (WRK_BLANKS_SS <= WRKLEN1) THEN DO;
CALL TDSETLEN (GWL_PROC, GWL_RC,
CTR_COLUMN,
WRK_BLANKS_SS - 1);
END;
/* --------------------------------------------------------*/
/* send a row to the client */
/* --------------------------------------------------------*/
CALL TDSNDROW (GWL_PROC, GWL_RC);
PARM_RETURN_ROWS = PARM_RETURN_ROWS + 1;
IF GWL_RC = TDS_CANCEL_RECEIVED THEN
DO;
ALL_DONE = ALL_DONE_YES;
END;
END;
ELSE IF SQLCODE = +100 THEN
DO;
ALL_DONE = ALL_DONE_YES;
END;
ELSE IF SQLCODE < 0 THEN
DO;
ALL_DONE = ALL_DONE_YES;
CALL FETCH_ERROR;
END;
RETURN;
END FETCH_AND_SEND_ROWS;
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, each 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.
Table 3-42 shows the conversions that TDSNDROW performs.
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 TDS CHAR |
TDSNUMERIC TDSNUMERIC |
Use TDSETBCD after TDESCRIB to set precision and scale for numeric and Sybase decimal columns. |
TDS_PACKED_DECIMAL TDSCHAR |
TDS_SYBASE_DECIMAL TDS_SYBASE_DECIMAL |
Use TDSETBCD after TDESCRIB to set precision and scale for numeric and Sybase decimal columns. |
TDSGRAPHIC TDSGRAPHIC TDSVARYGRAPHIC TDSVARYGRAPHIC |
TDSCHAR TDSVARYCHAR TDSCHAR TDSVARYCHAR |
Performed by Japanese Conversion Module (JCM). 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. Call TDRESULT to put 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.
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.
Related functions
