RTVCLPVAR       RETRIEVE CLP VARIABLES                 TAACLQH

 The  Retrieve CLP  Variables command  retrieves  the information  about
 the variables  used in a CL program source  member.  The information is
 passed back in two arrays.

   **   RTNVAR.   Contains one array  element for each variable declared
        in the program.   Each variable is 11  bytes and is preceded  by
        an &.

   **   RTNVAL.   Contains the attributes  of the variable defined  in a
        data  structure.  An  indication also exists if  the variable is
        passed into  the program as  a parameter  or comes  from a  DCLF
        definition.  Each element is 19 bytes.

 A typical use would be:

              DCL         &RTNVAR *CHAR LEN(5500)
              DCL         &RTNVAL *CHAR LEN(9500)
              DCL         &NBRVAR *DEC LEN(3 0)
               .
              RTVCLPVAR   MBR(xxx) SRCFILE(yyy) RTNVAR(&RTNVAR) +
                            RTNVAL(&RTNVAL) NBRVAR(&NBRVAR)

 Up to 500 variables  may exist in the program.  Source  files up to 240
 bytes may be used.

 The arrays  are loaded from the back  (for performance reasons) meaning
 the first variable  found in  the program is  at the  500th element  of
 each array.   The NBRVAR  parameter may be  used to determine  when all
 of  the elements have  been processed or  to start a  lookup operation.
 The unused values in both arrays are blank.

 The  RTNVAL array has a  data structure for each  19 byte element where
 all of the fields are character:

        Type          1 -  5    *CHAR or *DEC
        Length        6 - 10
        Decimals     11 - 12
        Passed in    13 - 13    Blank or P = Passed in as a parm
        File defn    14 - 14    Blank or F = defined by a DCLF
        Data Struct  15 - 15    Blank or X = DS (Stg defined over)
        Reserved     16 - 16

 If a field  is defined by both  a DCL and a  DCLF file statement,  an F
 will appear as being defined by the file.

 DCLVARP file in QTEMP
 ---------------------

 During  the  running of  RTVCLPVAR,  the  DCLVARP  file is  created  in
 QTEMP.    This  file  is updated  each  time  a  new  source member  is
 retrieved.  Before reading  the source, the file  is checked to see  if
 the  information   already  exists.     This  provides   a  significant
 improvement  in  speed  when  repeated  checking  of  the  same  source
 occurs.

 Handling of CL syntax
 ---------------------

 There are no restrictions on the CL  syntax used as long as the  source
 can be  used to  create a CL  program (see  the exception  for DEFVAR).
 For  example, you  may  declare variables  using any  of  the following
 type of syntax:

              DCL        VAR(&CHAR1) TYPE(*CHAR) LEN(5)
              DCL        TYPE(*CHAR) LEN(5) VAR(&CHAR1)
              DCL        &CHAR1 TYPE(*CHAR) LEN(5)
              DCL        &CHAR1 (*CHAR) LEN(5)
              DCL        &CHAR1 *CHAR (5)
              DCL        &CHAR1 *CHAR 5
              DCL        &CHAR1 *CHAR
              DCL        VAR(&DEC1) TYPE(*DEC) LEN(5)
              DCL        VAR(&DEC1) TYPE(*DEC) LEN(5 0)
              DCL        &DEC1 *DEC 5
              DCL        &DEC1 *DEC (5 0)

 If  a DCLF  statement is  used in  the program,  the DSPFFD  command is
 used to extract the  field definitions and add  them to the array.   If
 the  file used  on the  DCLF cannot  be found,  TAA9897 is  sent  as an
 escape  message.  A command  option exists to prevent  the error if the
 external object does not exist.

 Qualified variable names caused by  using a specific name for the  DCLF
 OPNID parameter  are not considered.   Only the unqualified  portion is
 used.   If a difference  in definition exists, the  last DCL definition
 is used.

 CL Data Structures - Use of DEFVAR Keyword
 ------------------------------------------

 Both the Data Structure  name and the sub  variable names are  returned
 as normal  variables.   The Data Structure  name is  flagged as  a Data
 Structure.

 Two  optional return variables  are available  to return  the variables
 used  in each Data  Structure and a count  of how many  exist.  See the
 DSSUBVAR and DSSUBNBR parameters.

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

    MBR           The CL source  member to be  retrieved from.  It  must
                  be a type CLP or CLLE.

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

    RTNVAR        A required  return variable which  is an array  of 500
                  11 byte  elements.  The array is  loaded from the back
                  meaning the  first variable  found in  the program  is
                  the 500th  element in the  array.  Each  variable name
                  is preceded  by an &.   The variable  must be declared
                  as *CHAR LEN(5500).

    RTNVAL        A  required return variable  which is an  array of 500
                  19 byte elements.   Each element is a data  structure.
                  See  the  previous information  on  the  layout.   The
                  array  is  loaded  from  the  back  meaning  the first
                  variable found  in the  program is  the 500th  element
                  in  the  array.   The  variable  must be  declared  as
                  *CHAR LEN(9500).

    NBRVAR        An  optional   return  variable  which  describes  the
                  number of elements  in the array.   If specified,  the
                  variable must be declared as *DEC LEN(3 0).

    NBRPRM        An  optional  return  variable   which  describes  the
                  number  of   parameters  that  are   passed  into  the
                  program  on  the  PGM statement.    If  specified, the
                  variable must be declared as *DEC LEN(3 0).

    DSSUBVAR      An optional return  variable which describes  the Data
                  Structure  names and  sub  fields (if  any) caused  by
                  use  of  the DCL  command  DEFVAR keyword.    There is
                  room for 490  entries with each entry  22 bytes.   The
                  array is  built from  the back end  and sorted  so the
                  lowest  alpha Data  Structure name  will be  the first
                  entry following blank values  (if any).  The  DSSUBNBR
                  describes the number of entries.

                  Each entry  is made up  of a  Data Structure name  (11
                  bytes) and a sub field name (11 bytes).

                  This  is  an optional  return  variable  that if  used
                  must be specified as *CHAR LEN(9900).

    DSSUBNBR      An   optional  return  variable  which  describes  the
                  number of entries  passed back in  DSSUBVAR.  Zero  is
                  returned if there are no Data Structures.

                  If a  number exists, it  may be used to  determine the
                  first  entry  in  DSSUBVAR.   For  example,  if  10 is
                  returned, the first entry  starts at element 481  (490
                  - 10 +  1) or position 9681  ((9900 + 1 -  (10 * 22)).

                  This  is  an  optional return  variable  that  if used
                  must be specified as *DEC LEN(5 0).

    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.

 Calling the CPP Directly
 ------------------------

 You  may call  the  CPP directly.    The following  RPG  code would  be
 typical:

      E                    VAR       500 11   VAL    19   Return arrays
      .
      IDCLDS       DS
      I                                        1   5 VRTYPE
      I                                        6  10 VRLEN
      I                                       11  12 VRDEC
      I                                       13  13 VRPRM
      I                                       14  14 VRFILE
      .
      C                     CALL TAACLQHR                   RTVCLPVAR
      C                     PARM           MBR    10        Member
      C                     PARM           FULFIL 20        Source file
      C                     PARM           VAR              Var names
      C                     PARM           VAL              Var values
      C                     PARM           NBRVAR  30       Nbr of vars
      C                     PARM           NBRPRM  30       Nbr of parms
      .
      C                     MOVELVAL,VX    DCLDS            Move to DS

 If  you are  going to use  the arrays  for lookup purposes,  you should
 start the lookup using the NBRVAR value as the starting location.

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

   **   Because return  variables  are used,  the  command may  only  be
        used in a CL program.

   **   The source  must be valid.   That is it  must be able  to create
        an error  free CL program.   No DCL  or DCLF commands  can exist
        after the first command.

   **   The  DEFVAR keyword must be used  to define the variable that is
        used as a data structure.

   **   A  previous  discussion  describes  the  valid  syntax  for  DCL
        commands  that  have been  tested.    It  is probable  that  the
        technique  used to  extract the  information from the  source is
        not a 100%  match with the  technique used by  the CL  compiler.
        For example,  if the VALUE keyword  is used, appears  before the
        other  keywords,  it may  contain characters  that  will confuse
        the search technique.

   **   Qualified variable names  caused by  using a  specific name  for
        the  DCLF  OPNID  parameter  are  not   considered.    Only  the
        unqualified  portion is  used.   If  a difference  in definition
        exists, the last DCL definition is used.

   **   A CL statement cannot exceed 5000 bytes.

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

 The following TAA Tools must be on your system:

      HLRMVMSG        HLL Remove message
      SNDDIAGMSG      Send diagnostic message
      SNDESCMSG       Send escape message

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

 None, the tool is ready to use.

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

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

    RTVCLPVAR     *CMD                   TAACLQH       QATTCMD
    TAACLQHC      *PGM       CLP         TAACLQHC      QATTCL
    TAACLQHC2     *PGM       CLP         TAACLQHC2     QATTCL
    TAACLQHR      *PGM       RPG         TAACLQHR      QATTRPG
    TAACLQHR2     *PGM       RPGLE       TAACLQHR2     QATTRPG
    TAACLQP       *FILE      PF          TAACLQHP      QATTDDS

Added to TAA Productivity Tools April 1, 1995


Home Page

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.