The Retrieve RPG Fields command returns the fields defined in an RPG
program.
A typical command would be:
DCL &RTNFLD *CHAR LEN(9990)
DCL &RTNVAL *CHAR LEN(9990)
DCL &RTNFLD2 *CHAR LEN(9990)
DCL &RTNVAL2 *CHAR LEN(9990)
DCL &NBRFLD *DEC LEN(5 0)
.
RTVRPGFLD MBR(xxx) SRCFILE(yyy) RTNFLD(&RTNFLD) +
RTNVAL(&RTNVAL) RTNFLD2(&RTNFLD2) +
RTNVAL2(&RTNVAL2) NBRFLD(&NBRFLD)
The RTNFLD variable contains the first 999 field names. The variable
is designed for array processing with the first field found in the
999th element (positions 9981-9990), the second field in the 998th
element (positions 9971-9980), etc. The NBRFLD variable contains the
number of fields found (if you use a LOKUP operation, you should
initialize the index to 999 - NBRFLD + 1).
Two additional sets of fields may be specified to return a maximum of
3996 fields from a source member.
Because the array elements are 10 bytes, the name size for RPG IV is
restricted to a maximum of 10. Field name sizes greater than 10 are
ignored. A message will appear at the bottom of the listing if
DSPRPGFLD is used.
The RTNVAL variable is designed for alternate array processing. The
values for the first field are in the 999th element (positions
9981-9990). Each element is a 10 byte array which is defined as
follows:
1 - 1 Field type
C = Char
P = Packed decimal
B = Binary
S = Zoned decimal
X = Constant
K = Key list
N = *NAMV
V = Variable length
2 - 6 Field length (See later discussion)
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
An Externally described file or data structure may be used, but the
object must be on the library list to access the definition. A
command option exists to prevent an error if the external object does
not exist.
/COPY is valid to access other source members to contribute to the
field definitions, but must be the same type as the original member.
For example, an RPGLE original member can /COPY another RPGLE type,
but not an RPG type. Any copied in members may not contain a /COPY
statement (No embedded /COPY statements). /INCLUDE is supported in
the same manner.
The RPG specifications must be valid. The correct syntax must be
used and the code must compile into a program without any assumed
field definitions.
Indicators are not considered.
Keylist names will not have an associated length.
RPG ILE lower case is translated to upper case so that all field
names will be returned in upper case.
An option exists to allow the DSPFFD output of any externally
described files to be written to the EXTFLDP file in a named library.
RPGFLDP file in QTEMP
---------------------
During the running of RTVRPGFLD, the RPGFLDP 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.
Field length
------------
For character fields, the field length is the byte length.
For data structures, the field length is the length on the DS spec if
it exists. If not, it is the largest To position of a sub field.
For decimal fields, the field length is the digit length. If the
field is already defined as packed on input, the number of digits is
determined by doubling the byte length and subtracting one to account
for the sign.
For arrays, the byte length is used. This is the element length
times the number of elements. For decimal arrays, the byte length of
each element is used.
Field usage
-----------
The setting of the Field Usage field is determined according to
several internal rules. If a field is both 'used' and 'changed', it
will be marked with an 'X' as 'changed'.
** A blank normally means the field is defined on the input
specifications and not described elsewhere in the program. An
exception is made for Lx and Mx indicators on the field in
which case the field is considered 'used'. If an array
element is specified, the array index is considered used.
** A 'U' for 'Used' normally means that the field is used in a
calculation statement such as Factor 1 of an IF statement.
The field is not changed by an RPG statement. If an array
index is used, it is also considered 'used'.
** An 'X' for 'Changed' normally means the field is changed by a
calculation specification such as it is the RESULT field of a
MOVE operation. Several exceptions exist such as an array
index used in Factor 2 of a LOKUP operation is considered
changed. Any fields which have a 'blank after' on output
specifications will be considered 'changed'.
** If the field is 'input' or 'both in a display file, it is
considered changed. If the field is output in either a
printer or display file, it is considered 'used'.
If a field is a sub field of a data structure and the data structure
is changed, the sub field is not considered to be changed.
Command parameters *CMD
------------------
MBR The RPG member to be retrieved from. The member
type must be RPG, RPGLE, RPGMOD, or RPG38.
SRCFILE The qualified file name of the source file. The
library value defaults to *LIBL. *CURLIB may also
be used.
RTNFLD A required return variable which will contain the
field names. The variable is designed for array
processing with the first field found in the 999th
element (positions 9981-9990), the second field in
the 998th element (positions 9971-9980), etc. The
remaining positions will be blank. The variable
must be declared as *CHAR LEN(9990).
If more than 999 fields may exist, see the RTNFLD2
parameter.
RTNVAL A required return variable which will contain the
corresponding definition of the fields in RTNFLD.
Each element is a data structure of information.
See the previous discussion of the definition.
The variable is designed for array processing with
the definition of the first field found in the 999th
element (positions 9981-9990), the second definition
in the 998th element (positions 9971-9980), etc.
The remaining positions will be blank. The variable
must be declared as *CHAR LEN(9990).
RTNFLD2 A required return variable which will contain the
field names for defined fields 1000-1998. The
variable must be declared as *CHAR LEN(9990).
RTNVAL2 A required return variable which will contain the
corresponding definition of the fields in RTNFLD2.
The variable must be declared as *CHAR LEN(9990).
RTNFLD3 A required return variable which will contain the
field names for defined fields 1999-2997. The
variable must be declared as *CHAR LEN(9990).
RTNVAL3 A required return variable which will contain the
corresponding definition of the fields in RTNFLD3.
The variable must be declared as *CHAR LEN(9990).
RTNFLD4 A required return variable which will contain the
field names for defined fields 2998-3996. The
variable must be declared as *CHAR LEN(9990).
RTNVAL4 A required return variable which will contain the
corresponding definition of the fields in RTNFLD4.
The variable must be declared as *CHAR LEN(9990).
NBRFLD An optional return variable which will contain the
number of fields returned. This will be a number
between 0-3996. If specified, the variable must be
declared as *DEC LEN(5 0).
SRCTYP An optional return variable which will contain the
source type of the RPG member retrieved from. If
specified, the variable must be declared as *CHAR
LEN(10).
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.
EXTFLDPLIB Determines if the DSPFFD output used to access the
definition of any externally described fields should
be copied to the EXTFLDP file. *NONE is the
default, meaning the DSPFFD outfile is written over
for each externally described file used in the
program and is of no value at the end of the
RTVRPGFLD command.
A library (such as QTEMP) may be named which will
contain all of the DSPFFD output used. For each
externally described file used in the program, the
DSPFFD output is added to the EXTFLDP file in the
named library. The EXTFLDP file is deleted and
recreated each time the RTVRPGFLD command is run
where a library is named.
The EXTFLDP file uses the same format as the outfile
for DSPFFD (QADSPFFD model outfile with QWHDRFFD
format) and has a key on field name and type of file
(descending sequence).
Restrictions
------------
Because the command returns variables, it may only be used in a CL
program.
Up to 3996 fields may be defined in the program.
Any names that exceed 10 bytes in length are ignored. A message will
appear at the bottom of the listing if DSPRPGFLD is used.
Any qualified data structure names are ignored.
An Externally described file or data structure may be used, but the
object must be on the library list to access the definition.
The parameters passed on a CALLP are ignored.
/COPY is valid to access other source members to contribute to the
field definitions, but must be the same type as the original member.
Any copied in members may not contain a /COPY statement. (No
embedded /COPY statements). /INCLUDE is supported in the same
manner.
The RPG specifications must be valid. The correct syntax must be
used and the code must compile into a program without any assumed
field definitions.
Indicators are not considered.
Arrays are described as the total length. A maximum of 99999 exists.
Also see the discussion under Field Usage.
It is not expected that RTVRPGFLD will be able to properly comprehend
every possible RPG syntax. Significant testing has occurred, but it
is probable that additional function is needed or additional
restrictions.
Prerequisites
-------------
The following TAA Tools must be on your system:
SNDESCMSG Send escape message
HLRMVMSG HLL Remove message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
RTVRPGFLD *CMD TAARPGK QATTCMD
TAARPGKC *PGM CLP TAARPGKC QATTCL
TAARPGKC2 *PGM CLP TAARPGKC2 QATTCL
TAARPGKC3 *PGM CLP TAARPGKC3 QATTCL
TAARPGKR *PGM RPG TAARPGKR QATTRPG
TAARPGKR2 *PGM RPG TAARPGKR2 QATTRPG
TAARPGKR3 *PGM RPG TAARPGKR3 QATTRPG
TAARPGKP *FILE PF TAARPGKP QATTDDS
TAARPGKQ *FILE PF TAARPGKQ QATTDDS
Structure
---------
RTVRPGFLD Cmd
TAARPGKC CL pgm
TAARPGKR3 RPG pgm - Retrieves and stores DCL stmts in RPGFLDP
Used to improve performance if re-used
TAARPGKR RPG pgm - OPM types
TAARPGKC2 CL Pgm - Does DSPFFD to outfile
TAARPGKC3 CL Pgm - Does CHKOBJ and returns OVR cmd
TAARPGKR2 RPG pgm - ILE types
TAARPGKC2 CL Pgm - Does DSPFFD to outfile
TAARPGKC3 CL Pgm - Does CHKOBJ and returns OVR cmd
|
