Receives a language string from a remote client.
%INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 HOST_VARIABLE CHAR(n), 01 MAX_VAR_LENGTH FIXED BIN(31), 01 ACTUAL_STRING_LENGTH FIXED BIN(31);
CALL TDRCVSQL (TDPROC, RETCODE, HOST_VARIABLE,
MAX_VAR_LENGTH, ACTUAL_STRING_LENGTH);
(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-26.
(O) Host program variable where the text of the retrieved language string is stored.
(I) Maximum length of the string that can be stored in the named HOST_VARIABLE. For graphic datatypes, this is the number of double-byte characters; for other datatypes, it is the number of bytes.
(O) The actual length of the incoming data. If this length is greater than the specified MAX_VAR_LENGTH, the data is truncated.
If this is a Japanese character set, the length may
be halved when converted to IBM Kanji by Gateway-Library.
The RETCODE argument can contain any of the return values listed in Table 3-26.
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_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) |
Wrong length. The length specified in the MAX_VAR_LENGTH argument is too short. |
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_NO_SQL_PRESENT (101) |
No incoming language string present. TDRCVSQL cannot retrieve more text because no more text was accepted. The operation failed. |
TDS_TRUNCATION_OCCURRED (-13) |
Data was truncated. The actual data length was longer than the maximum data length allotted for this data. |
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 the use of TDRCVSQL to receive a SQL language request from the client. This example is taken from the sample program in Appendix C, “Sample Language Application for CICS.”
/*------------------------------------------------------------------*/
READ_IN_SQL_TEXT:
/*------------------------------------------------------------------*/
/* ------------------------------------------------------------*/
/* prepare for receive */
/* ------------------------------------------------------------*/
CALL TDRESULT (GWL_PROC, GWL_RC);
/* ------------------------------------------------------------*/
/* load ptr to redefined sql text */
/* ------------------------------------------------------------*/
LANG_BUFFER_PTR = ADDR(LANG_BUFFER_DB2);
/* ------------------------------------------------------------*/
/* get len of language text, ensure not too big for us */
/* (this could be handled without TDSQLLEN by checking */
/* LANG_ACTUAL_LEN doesn't exceed LANG_MAX_L in TDRCVSQL call) */
/* ------------------------------------------------------------*/
CALL TDSQLLEN (GWL_PROC, GWL_SQLLEN);
LANG_MAX_L = STG(LANG_BUFFER_TEXT);
IF GWL_SQLLEN > LANG_MAX_L THEN
DO;
MSG_TEXT = MSG_BAD_LEN;
MSG_TEXT_L = STG(MSG_BAD_LEN);
CALL SEND_ERROR_MESSAGE;
GO TO END_PROGRAM;
END;
/* ------------------------------------------------------------*/
/* get language text */
/* ------------------------------------------------------------*/
CALL TDRCVSQL (GWL_PROC, GWL_RC,
LANG_BUFFER_TEXT,
LANG_MAX_L,
LANG_ACTUAL_L);
LANG_BUFFER_LL = LANG_ACTUAL_L;
A server application uses this function to retrieve a SQL or other language string from a client. Although the function is called TDRCVSQL, it can receive any type of language request, including math functions, single-byte katakana, and so on.
TDRCVSQL does not differentiate between SQL strings and other character text strings. Your application must determine what kind of text is in the buffer and what to do with it.
You can determine the length of the incoming string by issuing TDSQLLEN after TDACCEPT and before TDRCVSQL.
To determine whether the incoming request is a language request, cursor request, or an RPC, call TDINFPGM or TDRESULT. In long-running transactions, TDGETREQ indicates the type of request.
If your program calls TDRCVSQL and the request is not a language or cursor/dynamic request, TDRCVSQL returns TDS_NO_SQL_PRESENT.
You can divide the language string between two variables. First, specify a partial length in the MAX_VAR_LENGTH argument of one TDRCVSQL call. Then, issue TDSQLLEN just before conversion to determine the length of the remaining text, and specify that length in the MAX_VAR_LENGTH argument of a subsequent TDRCVSQL call.
If you are using a double-byte character set, see instructions
under “For Japanese Users” to learn how to divide
a string between two variables.
If the ACTUAL_STRING_LENGTH of the text is longer than that specified in MAX_VAR_LENGTH, the string is truncated, and TDRCVSQL returns TDS_TRUNCATION_OCCURRED.
To divide a language string between two variables when using double-byte character sets, set MAX_VAR_LENGTH to two times the length returned by TDSQLLEN.
Related functions
