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
|
