TAA Tools
RTVRPGCALL      RETRIEVE RPG CALL PARAMETERS           TAARPGP

The  Retrieve RPG  Call Parameters  command  retrieves the  information
about  the parameters  used for  a specific  CALL  operation in  an RPG
source member.  The information is passed back in two arrays.

  **   RTNPRM.    Contains the  field names  used  as parameters  for a
       specific Call  operation.   There  is  room for  100  parameters
       (the system  has a  limit that is  much smaller).   The intended
       use is  to be processed as an array.   Each element is 10 bytes.
       The array is built in  inverse order (the information about  the
       first parameter is at element 100).

  **   RTNVAL.  Contains  the attributes of the parameter  defined in a
       data  structure.   This is  intended as  an alternate  array for
       the RTNPRM value.   Each  element is 10  bytes.   See the  later
       definition of the data structure.

A typical command would be:

             DCL        &RTNPRM *CHAR LEN(1000)
             DCL        &RTNVAL *CHAR LEN(1000)
             DCL        &NBRPRM *DEC LEN(3 0)
              .
             RTVRPGCALL MBR(xxx) SRCFILE(yyy) PGM(ABC) +
                          RTNPRM(&RTNPRM) RTNVAL(&RTNVAL) +
                          NBRPRM(&NBRPRM)

The command is used by the DSPRPGCALL tool.

It is valid to specify  *ALL or *FIRSTCALL for a program  that does not
have  any parameters  being passed  to  it.   In this  case  the NBRPRM
return variable will contain 0.

Escape messages
---------------

Escape messages you may wish to monitor for are:

   TAA9883       A  required Externally  Described file  does not exist
                 on the library list.

   TAA9894       The sequence  number  does not  exist  or is  not  the
                 first record of a statement.

   TAA9895       No CALL commands were found.

   TAA9896       No  CALL  command was  found  for  a specific  program
                 name.

   TAA9897       The  command found  at  the specified  sequence number
                 is not a CALL command.

Data structure for RTNVAL
-------------------------

         1 - 1   Field type
                      C = Char
                      P = Packed decimal
                      B = Binary
                      S = Zoned decimal
                      X = Constant
                      K = Key list
                      N = *NAMV
         2 - 6   Field length
         7 - 8   Number of decimals (blank for character types)
         9 - 9   Field use (See later discussion)
                    Blank = Unused (only defined in the program)
                      U   = Used (only used in the program)
                      X   = Changed (some change occurs in the program)
        10 - 10  Field code
                    Bit 0 is on for Externally Described
                    Bit 1 is on for PLIST Parameter
                    Bit 3 is on for an Array
                    Bit 4 is on for a Data Structure
                    Bit 5 is on for a Data Structure sub field

For a complete understanding of the information in the
data structure, see the RTVRPGFLD tool.

Command parameters                                    *CMD
------------------

   MBR           The member  to be  retrieved from.    Only RPG  source
                 types are supported.

   SRCFILE       The  qualified file  name  of the  source  file.   The
                 file   defaults  to   QRPGSRC.    The   library  value
                 defaults to *LIBL.  *CURLIB may also be used.

   CALLNAME      The value in  Factor 2  to identify the  CALL Op  code
                 to be  used or  the source  sequence number where  the
                 CALL  exists.    Three  possible  entry types  may  be
                 made:

                 1)  The default is *FIRSTCALL  which should be used if
                 you want the first or only CALL in the source.

                 2) The value of Factor  2 on the CALL statement.   The
                 first  value that matches  will be  used.   The string
                 of  data  placed  in the  parameter  is  used  to scan
                 against Factor 2 of a CALL Operation code.

                 Therefore if you have a  literal as the program  name,
                 specify the literal  value.  If you have  a field name
                 as  the program  name, specify the  field name.   This
                 value is intended for when  there is a unique Call  in
                 the program that is not the first CALL operation.

                 3) The statement  number of the  CALL operation.   A 6
                 digit entry  must be used with all  digits entered and
                 no   decimal  point.     For  example,   if  the  CALL
                 operation is  150.00  in SEU,  specify  015000 as  the
                 statement number.   The  statement number  is intended
                 for  the case  where  you have  multiple calls  to the
                 same program name  and you need to  be specific.   See
                 also the NXTCALL parameter.

   RTNPRM        A  required  return  variable that  will  contain  the
                 field  names used  as parameters  for a  specific Call
                 operation.   There is  room  for 100  parameters  (the
                 system  has  a  limit that  is  much  smaller).    The
                 intended  use is to  be processed  as an array.   Each
                 element  is 10 bytes.   The array  is built in inverse
                 order (the  first parameter is  at element  100.   The
                 variable must be specified as *CHAR LEN(1000).

   RTNVAL        A  required  return  variable  that will  contain  the
                 corresponding  field  attributes  of  the  parameters.
                 This  is  intended  as  an  alternate  array  for  the
                 RTNPRM value.   Each  element is  10 bytes.   See  the
                 previous  discussion  of the  data  structure  that is
                 returned for  each parameter.   The  variable must  be
                 specified as *CHAR LEN(1000).

   NBRPRM        An  optional return  variable  that will  contain  the
                 number  of parameters  returned in  the  RTNPRM value.
                 If used, it must be specified as *DEC LEN(3 0).

   FACTOR2       An  optional  return  variable that  will  contain the
                 value  of  Factor  2  of  the  Call  Operation.    The
                 intended   use  of   this  value   is  to   assist  in
                 displaying  which Call is  being described.   If used,
                 it must be specified as *CHAR LEN(14).

   RTNPGM        An optional  return  variable that  will  contain  the
                 value of  the program  name on  the Call operation  if
                 it  can be  determined.   If  a literal  is  used, the
                 return program  appears  without  surrounding  quotes.
                 If a  field  name is  used which  is  a constant,  the
                 program  name is  attempted to  be extracted  from the
                 constant  value.  If a field  name is used that is not
                 a constant,  the  program  name cannot  be  determined
                 and  the value will  be blank.   If  used, it  must be
                 specified as *CHAR LEN(10).

   RTNPGMLIB     An  optional  return variable  that  will  contain the
                 value  of  the  program  library  name  on   the  Call
                 operation if  it can  be determined.   If  a qualified
                 program  name   is  used  as  a  literal,  the  return
                 program library  appears without  surrounding  quotes.
                 If a  field  name is  used which  is  a constant,  the
                 program  library  name is  attempted  to be  extracted
                 from  the constant  value.  If  an unqualified program
                 name is  used  as  a literal  or  in a  constant,  the
                 return library value  will be blank.  If  a field name
                 is  used that is  not a constant,  the program library
                 cannot be  determined and  the  value will  be  blank.
                 If used, it must be specified as *CHAR LEN(10).

   PGMSTMT       An  optional return  variable  that  will contain  the
                 sequence  number  of  the  statement  where  the  Call
                 operation was found.   If used,  it must be  specified
                 as *CHAR LEN(6).

   CALLOP        An  optional return  variable  that will  contain  the
                 Call operation  found on the  statement.  If  used, it
                 must be specified as *CHAR LEN(10).

   NXTCALL       A  *YES/*NO parameter  for whether the  Call after the
                 Source  Statement number  specified  in  the  CALLNAME
                 parameter  should  be  used.     *NO  is  the  default
                 meaning  that  the  specific  Statement  number  named
                 contains the Call Operation code to use.

                 *YES may  only be  specified when  a Statement  number
                 is  named for  the  CALLNAME parameter.    If *YES  is
                 specified,  the  source is  read  until  the statement
                 number is  found  and  then  the  search  for  a  Call
                 begins on the next statement.

                 The intent  of the *YES  value is  to allow a  calling
                 program to  access all of the Call  commands and their
                 parameter  lists  used in  a program.   This  would be
                 done by  first asking  for *FIRSTCALL  and then  using
                 the returned  value for PGMSTMT as  the CALLNAME value
                 along with NXTCALL(*YES).

   RQDEXTDSC     Determines  whether  any  externally  described  files
                 are  required.     *YES  is  the   default.    If   an
                 Externally  Described   file  is   specified  in   the
                 source,  it  must  exist on  the  library  list or  an
                 escape message will occur.

                 *NO may be  specified in which  case if an  Externally
                 Described file  exists, the  field specifications  are
                 used.    If  an  Externally  Described file  does  not
                 exist,  no  error  occurs, but  the  information about
                 some of the fields may be missing.

Restrictions
------------

Because the  command returns variables,  it may  only be used  in a  CL
program.

The tool relies  on the RTVRPGFLD tool which  has several restrictions.

The *ENTRY parameters may not be defined by a /COPY statement.

Prerequisites
-------------

The following TAA Tools must be on your system:

     EDTVAR          Edit variable
     HLRMVMSG        HLL Remove message
     RPGSTSDS        RPG Status DS
     RTVRPGFLD       Retrieve RPG fields
     SNDESCMSG       Send escape message

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   RTVRPGCALL    *CMD                   TAARPGP       QATTCMD
   TAARPGPC      *PGM       CLP         TAARPGPC      QATTCL
   TAARPGPR      *PGM       RPG         TAARPGPR      QATTRPG
					

Added to TAA Productivity tools August 1, 1996


Home Page Up to Top