TAA Tools
RTVRPGFLD       RETRIEVE RPG FIELDS                    TAARPGK

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
					

Added to TAA Productivity tools August 1, 1996


Home Page Up to Top