TAA Tools
RTVCLPCALL      RETRIEVE CLP CALL PARAMETERS           TAACLQJ

The Retrieve  CLP Call Parameters  command retrieves the  attributes of
the  parameters passed  to a  CL or  CLLE program.   The  source member
must be specified.

A typical command would be:

             DCL        &RTNVAR *CHAR LEN(1100)
             DCL        &RTNVAL *CHAR LEN(5000)
             DCL        &NBRPRM *DEC LEN(3 0)
              .
             RTVCLPCALL MBR(xxx) SRCFILE(yyy) PGM(*FIRSTCALL) +
                          RTNVAR(&RTNVAR) RTNVAL(&RTNVAL) +
                          NBRPRM(&NBRPRM)

The  RTNVAR parameter is  an array of  100 11 byte  elements where each
element is a  variable name or  the value *CONSTANT  (if a constant  is
passed).

The RTNVAL  parameter is an  array of 100  50 byte elements  where each
element  is  a data  structure  which  contains the  attributes  of the
parameter and the first 34 bytes if a constant is passed.

Both arrays are  loaded from the  back meaning the  first parameter  is
placed  in  the  last  element   to  allow  faster  lookup  operations.
Although  the system  restricts the  number of  parameters that  can be
passed on a CALL to  less than 100, the  array size allows for  growth.

Both CALL and CALLPRC are supported.

The NBRPRM  parameter is  the number  of parameters that  exist.   This
can be  helpful in determining where  to start a lookup  operation.  If
no parameters are passed on the CALL, this value will be 0.

The  PGM parameter  defaults to  *FIRSTCALL meaning  the first  CALL or
CALLPRC statement found in the program.  You may also specify:

  **   A  specific name.    The  program  or variable  name  should  be
       specified.

  **   A statement number where the CALL or CALLPRC is to be found.

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

Escape messages you may wish to monitor for are:

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

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.

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

   MBR           The source member  to be read  to search for  the CALL
                 command.

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

                 Source files up  to 240 bytes  in length may be  read.

   PGM           The program  name on the CALL statement  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  (or CALLPRC) command
                 in the source.

                 2) The  name of a program on  the CALL statement.  The
                 first program  by the  specified  name will  be  used.
                 Any library qualifier  is ignored.  If the  program is
                 a variable  name, specify a leading &  for the program
                 name.   This  value is  intended for  when there  is a
                 unique Call  in  the program  that  is not  the  first
                 CALL statement.

                 3) The  statement number of  the CALL statement.   A 6
                 digit  entry must be used with  all digits entered and
                 no  decimal  point.     For   example,  if  the   CALL
                 statement  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.   If a
                 Call  command  has  continuation source  records,  the
                 statement  number of  the first  record must  be used.
                 See also the NXTCALL parameter.

   RTNVAR        A  required  return  variable  that  will  contain  an
                 array  of the  attributes of  the parameters  that are
                 passed  on  the Call.    The return  variable  must be
                 declared as  type *CHAR  LEN(1100).   Each element  is
                 11 bytes  long.   The array  is loaded  from the  back
                 with  the  first  element  found  placed in  positions
                 1090 - 1100.  Unused positions will be blank.

                 If a variable is  used as a  parameter, the name  will
                 be proceeded by a &.

                 If a  constant is used,  the value will  be *CONSTANT.

                 The  alternating  array with  the  attributes of  each
                 parameter is returned in the RTNVAL parameter.

   RTNVAL        A  required  return  variable  that  will  contain  an
                 array of  the attributes  of the  parameters that  are
                 passed  on the  call.   The  return  variable must  be
                 declared  as type  *CHAR LEN(5000).   Each  element is
                 50 bytes long  and represents a  data structure.   See
                 the later  definition.  The  array is loaded  from the
                 back   with  the   first   element  found   placed  in
                 positions 4951  -  5000.   Unused  positions  will  be
                 blank.

   NBRPRM        An  optional return  variable  that will  contain  the
                 number  of parameters being  passed on  the CALL.   If
                 specified,  the  variable  must  be  declared  as *DEC
                 LEN(3 0).

   PGMNAM        An optional  return  variable  that will  contain  the
                 the first  14 bytes  of the Call  (or CALLPRC).   This
                 helps  identify the  Call statement.   This  value may
                 be helpful if a specific  program name is not used  on
                 the  PGM statement.   If  a  variable is  used as  the
                 program  name, the variable name  including the & will
                 be returned.    If  specified, the  variable  must  be
                 declared as *CHAR LEN(14).

   RTNPGM        An  optional return  variable  that will  contain  the
                 the  name of  the program  being called  if it  can be
                 determined.    If a  variable is  used as  the program
                 name, the  name of  the program  cannot be  determined
                 and the value  will be blank.  If  the program name is
                 specified  in quotes, the quotes will  be removed.  If
                 specified, the  variable  must be  declared  as  *CHAR
                 LEN(10).

   RTNPGMLIB     An  optional return  variable  that  will contain  the
                 the  name of the  library of the  program being called
                 if it can  be determined.   If a variable  is used  as
                 the library  name, the name  of the program  cannot be
                 determined  and  the  value will  be  blank.   If  the
                 library  name is specified in  quotes, the quotes will
                 be  removed.   If  specified,  the  variable  must  be
                 declared as *CHAR LEN(10).

   PGMSTMT       An  optional return  variable  that  will contain  the
                 sequence  number of  the first  record where  the Call
                 command was found.   This  value may be  helpful if  a
                 specific  statement number  was  not used  on the  PGM
                 statement.     If  specified,  the  variable  must  be
                 declared as  *CHAR  LEN(6).    See  also  the  NXTCALL
                 parameter.

   RTNPGMVAR     An  optional return  variable  that will  contain  the
                 name  of  the  variable  used  for the  program  if  a
                 variable  is used.   If  specified, the  variable must
                 be declared as *CHAR LEN(11).

   RTNLIBVAR     An  optional return  variable  that will  contain  the
                 name  of  the  variable  used  for the  library  if  a
                 variable  is used.   If  specified, the  variable must
                 be declared as *CHAR LEN(11).

   CALLCMD       An optional  return  variable that  will  contain  the
                 the name  of the Call  command (CALL or  CALLPRC) that
                 is  used.     If  specified,  the   variable  must  be
                 declared as *CHAR LEN(10).

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

                 *YES may  only be  specified when  a Statement  number
                 is  named   for  the  PGM  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  PGM  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.

RTNVAL Data Structure
---------------------

Each 50 byte element is made up as follows:

       Type          1 -  5    *CHAR or *DEC
       Length        6 - 10
       Decimals     11 - 12
       Value        14 - 46    Value (up to 34 bytes)
       Reserved     47 - 50    Reserved

All values are returned in *CHAR form.

If a value  is passed surrounded  by apostrophes, the  apostrophes will
appear in  the Value, but the  length will be the actual  length of the
data.

If  a plus or  minus is passed  proceeding a decimal  value, the length
will not include the plus or minus.

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

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

Valid syntax of a Call command must be used.

The source member must be a CL or CLLE type.

The TAA  RTVCLPVAR command is used  to determine the  attributes of the
variables.  This command has restrictions.

A constant cannot exceed 256 bytes.

It  is not expected that  the technique used  to access the information
is a 100% match with the technique used by the system.

A maximum of 100 parameters is supported.

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

The following TAA Tools must be on your system:

     EDTVAR          Edit variable
     HLRMVMSG        HLL Remove message
     RTVCLPVAR       Retrieve CLP variables
     SNDESCMSG       Send escape message

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

None, the tool is ready to use.

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

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

   RTVCLPCALL    *CMD                   TAACLQJ       QATTCMD
   TAACLQJC      *PGM       CLP         TAACLQJC      QATTCL
   TAACLQJC2     *PGM       CLP         TAACLQJC2     QATTCL
   TAACLQJR      *PGM       RPG         TAACLQJR      QATTRPG
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top