TDRCVPRM

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.

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

PARM-ID

(I) Number of the parameter or cursor parameter to be received. Parameters are numbered sequentially with the first parameter number one.

HOST-VARIABLE

(O) Host program variable where the parameter data is stored.

HOST-VARIABLE-TYPE

(I) Datatype of the HOST-VARIABLE. This is the datatype that is used in mainframe processing of this parameter.

MAX-DATA-LENGTH

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

ACTUAL-DATA-LENGTH

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

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.

Example 2

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. 

Usage

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

Datatype conversions

Table 3-25 shows which implicit conversions can be performed by TDRCVPRM.

• Table 3-25: Datatype conversions 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.

For Japanese users

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

See also

Related functions

• TDACCEPT

• TDINFPRM

• TDLOCPRM

• TDNUMPRM

• TDRCVSQL

• TDSETPRM

Related topics

• “Character sets”

• “Datatypes”

• “Processing Japanese client requests”

---

Copyright © 2007. Sybase Inc. All rights reserved.

View this document as PDF