Retrieves the data from an RPC parameter sent by a remote client.
COPY SYGWCOB.
01 TDPROC PIC S9(9) USAGE COMP SYNC. 01 RETCODE PIC S9(9) USAGE COMP SYNC. 01 PARM-ID PIC S9(9) USAGE COMP SYNC. 01 HOST-VARIABLE PIC X(n). 01 HOST-VARIABLE-TYPE PIC S9(9) USAGE COMP SYNC. 01 MAX-DATA-LENGTH PIC S9(9) USAGE COMP SYNC. 01 ACTUAL-DATA-LENGTH PIC S9(9) USAGE COMP SYNC.
CALL 'TDRCVPRM' USING 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 or cursor 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. |
The following code fragment illustrates a typical use of TDRCVPRM. The transaction does the following: calls TDNUMPRM to determine how many parameters to retrieve; calls TDLOCPRM to ascertain the number of the parameter whose information it wants; calls TDINFPRM for a description of the parameter; calls TDRCVPRM to retrieve the parameter data. This example is taken from the sample program, SYCCSAR2, in Appendix B, “Sample RPC Application for CICS.”
* Get number of parameters ... should be two CALL 'TDNUMPRM' USING GWL-PROC, GWL-NUMPRM-PARMS. IF GWL-NUMPRM-PARMS NOT = 2 THEN PERFORM TDNUMPRM-ERROR GO TO END-PROGRAM END-IF. * Get return parameter information MOVE 1 TO GWL-INFPRM-ID. PERFORM GET-PARM-INFO. (IF GWL-INFPRM-STATUS NOT = TDS-RETURN-VALUE AND IF GWL-INFPRM-STATUS NOT = TDS-RETURN-VALUE-NULLABLE) THEN PERFORM TDINFPRM-NOT-RETURN-PARM-ERROR GO TO END-PROGRAM END-IF. MOVE GWL-INFPRM-USER-DATA TO GWL-SETPRM-USER-DATA. MOVE GWL-INFPRM-ID TO GWL-SETPRM-ID. MOVE GWL-INFPRM-DATA-L TO GWL-SETPRM-DATA-L. MOVE GWL-INFPRM-TYPE TO GWL-SETPRM-TYPE. * Get department id parameter number from known name MOVE '@parm2' TO GWL-INFPRM-NAME. MOVE 6 TO GWL-INFPRM-NAME-L. CALL 'TDLOCPRM' USING GWL-PROC, GWL-INFPRM-ID, GWL-INFPRM-NAME, GWL-INFPRM-NAME-L. * Get department parameter information PERFORM GET-PARM-INFO. IF GWL-INFPRM-TYPE NOT = TDSVARYCHAR THEN PERFORM TDINFPRM-NOT-CHAR-PARM-ERROR GO TO END-PROGRAM END-IF. * Get department parameter data CALL 'TDRCVPRM' USING GWL-PROC, GWL-RC, GWL-INFPRM-ID, PARM-DEPT, GWL-INFPRM-TYPE, GWL-INFPRM-MAX-DATA-L, GWL-RCVPRM-DATA-L. *----------------------------------------------------------------- GET-PARM-INFO. *----------------------------------------------------------------- CALL 'TDINFPRM' USING 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.
The following code fragment illustrates the use of TDRCVPRM in a Gateway-Library program that uses the IMS TM implicit API. This example is taken from the sample program in Appendix D, “Sample RPC Application for IMS TM (Implicit).”
* ------------------------------------------------------------ * establish gateway environment * ------------------------------------------------------------
CALL ‘TDINIT’ USING IO-PCB, GWL-RC, GWL-INIT-HANDLE. . . [check return code] . * ------------------------------------------------------------ * set program type to MPP * ------------------------------------------------------------
CALL ‘TDSETPT’ USING GWL-INIT-HANDLE, GWL-RC, GWL-PROG-TYPE, GWL-SPA-PTR, TDS-NULL, TDS- NULL.
. [check return code] . * ------------------------------------------------------------ * accept client request * ------------------------------------------------------------
CALL ‘TDACCEPT’ USING GWL-PROC, GWL-RC, GWL-INIT-HANDLE, SNA-CONNECTION-NAME, SNA-SUBC. . . [check return code] . *---------------------------------------------------------------- READ-IN-USER-PARM. *----------------------------------------------------------------
MOVE ‘Y’ TO SEND-DONE-SW. MOVE ‘N’ TO ALL-DONE-SW. MOVE SPACES TO CALL-ERROR. MOVE ZEROES TO CALL-ERROR-RC CTR-ROWS. MOVE 1 TO CTR-COLUMN. MOVE LENGTH OF PARM-DEPT TO WRKLEN1.
CALL ‘TDRCVPRM’ USING GWL-PROC, GWL-RC, PARM-ID1, PARM-DEPT, TDSCHAR, WRKLEN1, PARM-L.
IF GWL-RC NOT EQUAL TO ZEROES THEN MOVE ‘TDRCVPRM’ TO CALL-ERROR PERFORM DISPLAY-CALL-ERROR END-IF.
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 TDSCHAR |
When receiving numeric or Sybase decimal the 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 TDSCHAR |
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 this packed decimal. |
TDSCHAR TDSCHAR TDSVARYCHAR TDSVARYCHAR |
TDSGRAPHIC TDSVARYGRAPHIC TDSGRAPHIC TDSVARYGRAPHIC |
Used with Japanese double-byte character sets. 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-25 lists the implicit conversions that the JCM does when retrieving data.
Related functions
Related topics
Copyright © 2005. Sybase Inc. All rights reserved. |
![]() |