Retrieves the data from an RPC parameter sent by a remote client.
%INCLUDE SYGWPLI;
01 TDPROC PTR, 01 RETCODE FIXED BIN(31), 01 PARM_ID FIXED BIN(31), 01 HOST_VARIABLE CHAR(n), 01 HOST_VARIABLE_TYPE FIXED BIN(31), 01 MAX_DATA_LENGTH FIXED BIN(31), 01 ACTUAL_DATA_LENGTH FIXED BIN(31);
CALL TDRCVPRM (TDPROC, RETCODE, PARM_ID,
HOST_VARIABLE, HOST_VARIABLE_TYPE,
MAX_DATA_LENGTH, ACTUAL_DATA_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-24.
(I) Number of the parameter to be received. Parameters are numbered sequentially with the first parameter number one.
(O) Host program variable where the parameter data is stored.
(I) Datatype of the HOST_VARIABLE. This is the datatype that is used in mainframe processing of this parameter.
(I) Maximum length of the data that can be stored in the named HOST_VARIABLE. For TDSVARYCHAR, TDSVARYBIN, and TDSVARYGRAPHIC parameters, this value does not include the 2 bytes for the “LL” length specification.
For graphic datatypes, this is the number of double-byte characters. For a Sybase numeric or decimal parameter, it is 35. For other datatypes, it is the number of bytes.
To determine the maximum length of the incoming data, use TDINFPRM. For fixed-length datatypes, this value is ignored.
(O) Variable where the actual length of the received data is returned. For TDSVARYCHAR, TDSVARYBIN, and TDSVARYGRAPHIC parameters, this value does not include the 2 bytes for the “LL” length specification. If this length is greater than the specified MAX_DATA_LENGTH, the data is truncated, and TDRCVPRM returns TDS_ TRUNCATION_OCCURRED.
For graphic datatypes, this is the number of double-byte characters; for other datatypes, it is the number of bytes.
The RETCODE argument can contain any of the return values listed in Table 3-24.
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_ENTRY_NOT_FOUND (-8) |
The specified column number, transaction number, or parameter does not exist. |
TDS_FLOAT_CONVERSION_ERROR (-21) |
Error in conversion of float values. |
TDS_INVALID_DATA_CONVERSION (-172) |
Incompatible datatypes. The source datatype cannot be converted into the requested result datatype. |
TDS_INVALID_DATA_TYPE (-171) |
Illegal datatype. A Sybase datatype supplied in the call is not supported and the conversion cannot be done. The operation failed. |
TDS_INVALID_ID_VALUE (-10) |
The specified column or parameter number is greater than the system maximum. Sybase allows as many columns per table result and parameters per RPC as the system maximum. |
TDS_INVALID_LENGTH (-173) |
Wrong length. The length specified in the xxx-LENGTH argument is too long. |
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_INVALID_VAR_ADDRESS (-175) |
Specified variable address is invalid. No variable with the specified name exists. A NULL value was specified. The operation failed. |
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_NO_PARM_PRESENT (103) |
No incoming parameters present. TDRCVPRM cannot retrieve a parameter because no more parameters were 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. |
In the following code fragment, TDRCVPRM is called to receive the data in the first incoming parameter. This example is taken from the sample program in Appendix B, “Sample RPC Application for CICS.”
/*------------------------------------------------------------------*/
GET_PARMS:
/*------------------------------------------------------------------*/
/* ------------------------------------------------------------*/
/* get return parameter information */
/* ------------------------------------------------------------*/
GWL_INFPRM_ID = 1;
CALL GET_PARM_INFO;
(IF GWL_INFPRM_STATUS ^= TDS_RETURN_VALUE AND
IF GWL_INFPRM_STATUS ^= TDS_RETURN_VALUE_NULLABLE) THEN
DO;
CALL TDINFPRM_NOT_RETURN_PARM_ERROR;
GO TO END_PROGRAM;
END;
GWL_SETPRM_USER_DATA = GWL_INFPRM_USER_DATA;
GWL_SETPRM_ID = GWL_INFPRM_ID;
GWL_SETPRM_DATA_L = GWL_INFPRM_DATA_L;
GWL_SETPRM_TYPE = GWL_INFPRM_TYPE;
/* ------------------------------------------------------------*/
/* get department id parameter number from known name */
/* ------------------------------------------------------------*/
GWL_INFPRM_NAME = '@parm2';
GWL_INFPRM_NAME_L = 6;
CALL TDLOCPRM (GWL_PROC,
GWL_INFPRM_ID,
GWL_INFPRM_NAME,
GWL_INFPRM_NAME_L);
/* ------------------------------------------------------------*/
/* get department parameter information */
/* ------------------------------------------------------------*/
CALL GET_PARM_INFO;
IF GWL_INFPRM_TYPE ^= TDSVARYCHAR THEN
DO;
CALL TDINFPRM_NOT_CHAR_PARM_ERROR;
GO TO END_PROGRAM;
END;
/* ------------------------------------------------------------*/
/* get department parameter data */
/* ------------------------------------------------------------*/
CALL TDRCVPRM (GWL_PROC, GWL_RC,
GWL_INFPRM_ID,
PARM_DEPT,
GWL_INFPRM_TYPE,
GWL_INFPRM_MAX_DATA_L,
GWL_RCVPRM_DATA_L);
/*------------------------------------------------------------------*/
GET_PARM_INFO: PROC;
/*------------------------------------------------------------------*/
CALL TDINFPRM (GWL_PROC, GWL_RC,
GWL_INFPRM_ID,
GWL_INFPRM_TYPE,
GWL_INFPRM_DATA_L,
GWL_INFPRM_MAX_DATA_L,
GWL_INFPRM_STATUS,
GWL_INFPRM_NAME,
GWL_INFPRM_NAME_L,
GWL_INFPRM_USER_DATA);
RETURN;
END GET_PARM_INFO;
A server application calls TDRCVPRM to retrieve a parameter sent by a remote client. A server application uses TDRCVPRM only when the client request is an RPC or a cursor command. Language requests do not have parameters.
An application must issue one TDRCVPRM call for each parameter to be retrieved. To determine the total number of parameters received, use TDNUMPRM.
Parameters can be retrieved in any order, using the PARM_ID argument to specify which parameter is wanted. If you know the parameter name but not its number, call TDLOCPRM to determine the parameter ID.
Unless you already know the length and datatype of the incoming parameter, call TDINFPRM before each TDRCVPRM call. TDINFPRM returns the datatype and length of the incoming data, and indicates whether or not it is a return parameter.
If the ACTUAL_DATA_LENGTH is greater than the MAX_DATA_LENGTH, the data is truncated, and TDRCVPRM returns TDS_TRUNCATION_OCCURRED.
A server program can modify the data length of a return parameter by issuing TDSETPRM before it returns results.
If the parameter datatype is different from the one specified in HOST_VARIABLE_TYPE, TDRCVPRM converts it to the specified datatype before processing (implicit conversion).
Table 3-25 shows which implicit conversions can be performed by TDRCVPRM.
Source datatype: Open Client |
Result datatype: Gateway-Library |
Notes |
|---|---|---|
TDSCHAR TDSCHAR TDSVARYCHAR TDSVARYCHAR TDSLONGVARCHAR TDSLONGVARCHAR |
TDSVARYCHAR TDSLONGVARCHAR TDSCHAR TDSLONGVARCHAR TDSCHAR TDSVARYCHAR |
Performs ASCII to EBCDIC conversion. For Japanese character sets, does workstation to mainframe conversion. Pads TDSCHAR fields with blanks. |
TDSFLT4 TDSFLT4 TDSFLT8 TDSFLT8 |
TDSFLT8 TDS_PACKED_DECIMAL TDSFLT4 TDS_PACKED_DECIMAL |
Truncates low order digits. |
TDSMONEY TDSMONEY TDSMONEY4 TDSMONEY4 TDSMONEY TDSMONEY TDSMONEY |
TDSFLT4 TDSFLT8 TDSFLT4 TDSFLT8 TDSCHAR TDSVARYCHAR TDS_PACKED_DECIMAL |
|
TDSCHAR TDSVARYCHAR |
TDS_PACKED_DECIMAL TDS_PACKED_DECIMAL |
|
TDSNUMERIC TDSNUMERIC |
TDS_PACKED_DECIMAL TDS_CHAR |
When receiving numeric or Sybase decimal as char, MAX_DATA_LENGTH is the maximum length of the result (precision +2, or precision +3 if precision=scale). |
TDS_SYBASE_DECIMAL TDS_SYBASE_DECIMAL |
TDS_PACKED_DECIMAL TDS_CHAR |
When receiving numeric or Sybase decimal as packed decimal, use TDINFBCD to determine the host packed decimal precision and scale. MAX_DATA_LENGTH is the actual length of the packed decimal. |
TDSCHAR TDSCHAR TDSVARYCHAR TDSVARYCHAR |
TDSGRAPHIC TDSVARYGRAPHIC TDSGRAPHIC TDSVARYGRAPHIC |
Used with Japanese DBCS. Pads TDSGRAPHIC fields with blanks. |
TDSDATETIME TDSDATETIME4 |
TDSCHAR TDSCHAR |
For more information about datatypes, see “Datatypes”.
TDRCVPRM pads binary-type host variables with zeroes and graphic- or character-type host variables with blanks. No default padding is set for columns of other datatypes.
Open Client automatically converts all fixed character
(TDSCHAR) parameters to variable character
(TDSVARYCHAR) parameters when it sends them
to a server. If you prefer to work with fixed character parameters,
assign HOST_VARIABLE_TYPE a
value of TDSCHAR.
When the Japanese Conversion Module (JCM) is used, TDRCVPRM converts the parameter data from the client character set to the one used at the mainframe server, if conversion is necessary.
When converting client character data to mainframe graphic data, Gateway-Library divides the length of incoming Japanese strings in half because the length of mainframe graphic datatypes is the number of double-byte characters, whereas the length of character datatypes at both the mainframe and the workstation is the number of bytes.
Your program needs to allow for length differences between the workstation character set and the mainframe character set.
See “Processing Japanese client requests” and “Datatypes” for a full discussion of character set conversions and length considerations.
When using the JCM, an application can call TDSETSOI to manipulate Shift Out/Shift In codes for character data before issuing a TDRCVPRM call.
Table 3-24 lists the implicit conversions that the JCM does when retrieving data.
Related functions
Related topics
