TAA Tools

The  Create Subfile  Program  2  command  creates a  display  file  and
program (RPG or  RPGLE) which allows a display of  data from arrays.  A
'position  to'  function is  optional.   It is  expected that  you will
make modifications  to  the program  to build  your  own array,  detail
display, etc.

The TAA  Productivity Tools  product is required  to run  the generated

A typical subfile display would look like:

*                                                                    *
*                     TAA Create Subfile 2 Demo                      *
*                                                                    *
*   Position to:  *AUTL                                              *
*                 ----------                                         *
*                                                                    *
*   Type options, press Enter.                                       *
*     5=Display                                                      *
*                                                                    *
*   Opt  Code         Description                                    *
*    _   *AUTL        Authorization list                             *
*    _   *BINDIR      Binder directory                               *
*    _   *CLS         Class                                          *
*    _   *CMD         Command definition                             *
*    _   *CTLD        Controller description                         *
*                                                                    *
*   F3=Exit    F12=Cancel                                            *
*                                                                    *

The  'Position To'  field  at the  top is  optional to  re-position the
subfile.   The  '5  =  Display'  option  allows  you  to  display  more
information from an alternating array.

A  CRTSFLPGM2 parameter  exists  to  allow one  of  the  entries to  be
selected  and returned  as a  parameter value.   Using  this adds  '1 =
Select' as  an option  to the  display.   See the  section on  'Passing
back a selection'.

Typical uses of the tool would be:

  **   Display a series of  codes and descriptions such as  used in the
       sample  code   which  uses  compile   time  arrays.     See  the
       discussion on 'Using a compile time array.'

  **   Display  a series of codes and  descriptions from data stored in
       a data  base file.   See the  discussion on  'Using a data  base
       file to fill the arrays'.

  **   Invoke the subfile  program from one of your  programs and allow
       selection  of one of  the entries to  provide further processing
       on the return to your  program.  See the discussion on  'Passing
       back a selection'.

  **   Create  your   own  function   for  displaying   data  such   as
       extracting  it from  an API.   See the  discussion on  'Using an
       API to fill the arrays'.

CRTSFLPGM2 will create  the source  and objects  for you.   Unlike  the
CRTSFLPGM  tool, CRTSFLPGM2  assumes  you will  modify  the source  and
re-create  the objects.   No  re-create functions  are provided  for by
the  tool.  You must  use a source editor  and the system CRT commands.
For a  comparison with  CRTSFLPGM, see  the section  on 'Contrast  with

Getting started

  **   Determine the following:

         --   What data will be used for the arrays.

         --   Will the  array data be 'compile  time' source statements
              or   will    the   program   build   the   entries   from

         --   What source members and object  library will be used  for
              the display file and RPG program.

         --   Should RPG or RPGLE code be generated.

         --   Will the 'Position to' function be needed.

         --   Will the '1 = Select' option be needed.

  **   A  typical CRTSFLPGM2  command that  uses most  of the  defaults
       would be entered as:

                  CRTSFLPGM2     RPGMBR(xxx)

         --   The  name of  the RPG  member would be  used for  the RPG
              source member and program.   It is also the default  name
              for the display file source member and display file.

         --   By  default,  RPG  type  (not   RPGLE)  source  would  be
              generated to the QRPGSRC source file.

         --   The  display  file source  would  be  generated into  the
              QDDSSRC source file.

         --   REPLACE(*NO)  is  the default  so the  RPG or  DDS source
              member must  not  exist and  the  objects to  be  created
              must not exist.

         --   The display file  and RPG program would be  created.  The
              compile listings would be spooled.

  **   Call the program to see the results:

                  CALL   xxx

         --   Because  a 'Position to'  field was  requested by default
              (POSITION parameter), you can  enter a value to  position
              the subfile  to.   If the value  entered does  not exist,
              the  subfile  is positioned  to the  entry  preceding the
              value requested.  Roll  keys are valid  if more than  one
              page of  entries exists.   After  changing the  'Position
              to' value, either roll key may be used.

         --   The  ALWSELECT  default  of *NO  was  used  so  the '1  =
              Select' option does not appear.

         --   The  type of array (TYPE  parameter) defaults to *COMPILE
              so compile time  source statements are  used to fill  the

Generated source TAA identification

The generated DSPF  and RPG source will contain  the letters 'bTAAb' (b
=  blank)  in  the first  5  characters of  the  source  data (sequence
number columns).  This is  intended to assist in determining what  user
additions have been made to the source.

The intent is  that you be able  to identify any changes  you have made
such as:

  **   if  you change  an existing  line, you could  make it  a comment
       and add a new line with blanks for the first 5 characters.

  **   If you add a line, use blanks for the first 5 characters.

Contrast with CRTSFLPGM

CRTSFLPGM generates a subfile program and  uses data from a keyed  data
base file.   The typical  options of display,  change, add, and  delete
are   provided  for.      Tailoring   of  the   subfile   layout,  text
descriptions,  and  simple  validity  checking  is  provided  for.   An
option exists  for  a 'display  only' version.   You  may  not need  to
modify the generated source.

CRTSFLPGM2 uses  data in arrays  to display a  subfile.  Only the  '5 =
Display'  option is provided for  by default.  The  '1 = Select' option
may be  requested.   You  must modify  the  generated source  for  your
specific needs.

Passing back a selection

The ALWSELECT  parameter on  CRTSFLPGM2 allows  an option  so that  the
generated  program may  pass back  a  selected value.   The  default is

Specifying *YES would  allow you to  have a main  program that calls  a
CRTSFLPGM2  created  program  which  passes   back  a  selected  value.
Additional processing could then be done in the main program.

An  example of  this type  of approach  is used  by  the system  for F4
operations  which  allow you  to select  from a  list.   Two  TAA tools
allow a similar approach.   SELOBJ selects from  a list of objects  and
and SELMBR selects from a list of members.

When ALWSELECT(*YES)  is specified, the  '1 = Select' option  is valid.
The  first '1' entered as an  option causes the program  to end and the
selected value to be passed back as a parameter.

Because this function returns a  parameter, requesting *YES means  that
the  generated program  must  be  called by  a  program  that passes  a

The parameter is defined as *CHAR LEN(10), but may be changed.

If  no selection  is made, the  return parameter  will have a  value of

The following code shows an example of  CL code to use DSPFD to  create
a  member list  and  call a  CRTSFLPGM2  generated program  to  display
member  information  and  accept a  selected  member  on  return.   The
selected member is used in a message.

             DCL        &RTNCDE *CHAR LEN(8)
             DSPFD      FILE(xxx) TYPE(*MBRLIST) +
                          OUTPUT(*OUTFILE) OUTFILE(QTEMP/DSPFDP)
             CALL       yyy PARM(&RTNCDE)
             SNDPGMMSG  MSG(&RTNCDE)

CRTSFLPGM2 was specified with:

           TITLE('Access Source Members')

Changes  to the  generated display  file were  made to use  'Member' as
the column heading and detail display instead of 'Code'.

Changes to the  generated program were made  to use file QAFDMBRL  with
a  format name  of QWHFDML.   The  MLNAME field  was used  for  the COD
array and the MLMTXT was used for the DSC array.

When the program is called, the display appears as:

*                                                                     *
*                            Access Source Members                    *
*                                                                     *
*   Position to:  MBR1                                                *
*                 ----------                                          *
*                                                                     *
*   Type options, press Enter.                                        *
*     1=Select    5=Display                                           *
*                                                                     *
*   Opt  Member       Description                                     *
*    _   MBR1         The first member                                *
*    _   MBR2         The second member                               *
*    _   MBR3         The third member                                *
*         .            .                                              *
*                                                                     *
*   F3=Exit    F12=Cancel                                             *
*                                                                     *

Note  that if you  are using CRTSFLPGM2  to help the  end user identify
something like  a customer by  name, the  normal approach  would be  to
prompt the user to  enter some leading portion of  the customer name in
the main program and then call the CRTSFLPGM2 generated program.

The  ZZLOAD subroutine could  use a SETLL  to position to  the customer
name key and then start reading  records.  You probably want to  cutoff
after a  hundred or  so records  have been  read and  converted to  the
arrays to  see if the  name can be identified.   If not,  when the main
program  is returned  to with  a parameter  of *NONE, you  could prompt
again and ask for a more specific value.

General approach used in the generated program

Depending on the  TYPE parameter,  the array data  is either loaded  at
compile  time  or  done via  calculations.    The  default is  to  load
compile  time source statements as array  data.  Both approaches result
in the same arrays (COD and DSC).

The codes in the  COD array are defined as  10 bytes.  The  description
field in the DSC array is defined as 60 bytes.

The ZZCVT subroutine  is used for each  record before it is  written to
the  subfile.   Use this  to reformat any  data for  the display.   The
array  element  is  moved  from  the  DSC  array  to  the  ZZDSC   data
structure.    Using  this approach  allows  you  to  define  additional
fields  in the  ZZDSC data structure  and specify  them in  the display
file  source.   To make  changes, scan the  DDS source  for SUBFLDS and

The  '5  = Display'  option  also  uses  the  ZZCVT  subroutine  before
displaying the details of a record.

If additional fields  need to be displayed on  the detail display, scan
the DDS source for ZZDSP1 and add the fields.

The  COD array is  defined as having  1000 elements as a  maximum.  You
can change this value, but you  must allow room for one blank value  at
the end.   This is changed to *HIVAL during  the initialization routine
in  the  program.   If  you change  the  number of  elements,  scan for
ZZCODE and specify the number allowed in the array.

You may want  to change  the name  of the COD  and DSC  arrays to  make
them  more meaningful.    After  changing  the array  names,  scan  for
'COD,' and  'DSC,' for RPG source.   For RPGLE source,  scan for 'COD('
and 'DSC('

A  'page at a time' subfile  is used.  Each page  has 14 records (or 12
if a  'Position to'  line exists).   Rollup and  rolldown are  provided

Messages are  provided for  typical errors such  as an  invalid option,
rolldown  cannot be  performed, etc.   A message  subfile is  used.  To
add your own messages, see the section on 'Displaying messages'.

Basic help  text is  provided  for.   You may  need to  add  additional
help.  See the section on 'Help text'.

Using a compile time array

The simplest  requirement would  be to  replace the  array data in  the
generated  program with your own  requirements.  This  would be typical
of a  set of  values that  rarely changes.   See  the comments  in  the
'General approach' section about the COD and DSC arrays.

Using a data base file to fill the arrays

Using a data base  file to load the entries allows  more flexibility in
changing  the list because  it can be  done externally to  the program.
An  externally described  keyed data base  file may be  defined to hold
the data.   A tool such  as CRTSFLPGM may be  used to create  a program
that will provide maintenance of the data.

Using a keyed  file on the field  to be used for COD  is recommended as
an escape message will occur if the data is loaded out of sequence.

Rather  than  load the  arrays directly  using  simple RPG  syntax, the
ZZLOAD  subroutine  is  used  which  allows  you  more  flexibility  to
extract and format the data as required.

When using  CRTSFLPGM2, specify  TYPE(*CALC).   This will generate  the
standard  file TAASTDIQ and  causes code to  be inserted to  the ZZLOAD
subroutine.  Scan repeatedly for  CLCARR to find the required  changes.

If you have a simple  need and can use the supplied COD  and DSC arrays
as is, there should be no other changes required.

If  you have additional  fields for the  ZZDSC data structure  or other
additional  requirements,  you will  need  modifications to  the ZZLOAD

Using an API to fill the arrays

Many system  APIs exist  to allow  extracting of  information from  the
system.   These  provide call  level interfaces  with  parameter lists.
If  a  large  amount  of data  is  returned,  a  user  space object  is
normally used.

You can use an API to  extract information and then build the  required

Multiple keys

If you  have multiple keys  for 'Position to',  the COD array  could be
built with  a data structure.  You would need  to modify the prompt and
positioning fields.  ZKPOS1 is defined  in the DDS and in the  program.
Scan the DDS for ZZPOSTO.  Scan the RPG for ZKPOS1.

Modifying the '5 = Display' function

The supplied code  does a simple  display of the same  information that
appears in the subfile.

You  may have additional  information that  needs to be  displayed that
is  stored in the DSC  data structure.  These fields  could be added to
the ZZDSP1 format.

Another alternative is  to not use the  ZZDSP1 display and invoke  your
own  display function.   For  example,  if you  were displaying  member
information, you might use the DSPMBRD TAA command.

If you have your own function, you can:

  **   Leave  the  ZZDSP1 format  in the  display  file and  bypass the
       EXFMT statement.

  **   Drop the  ZZDSP1 format of  the display  file and  use your  own
       version  of the  ZZDSP0 subroutine.    If the  ZZDSP1 format  is
       deleted, you  should also delete the  help formats (ZZDSP1A1 and

Displaying messages

Messages for either information or  errors appear in a message  subfile
on lines 23  and 24 of various  displays.  Rollup is supported  if more
than 2 lines of messages exist.

The  message text  is  in the  RPG  source for  the  alternating arrays
ZZA/ZZB.   These messages use a  code of Znn.  If  you add some of your
own messages to the arrays, use a Unn code.

The messages  are sent  to the  message  subfile using  the message  ID
CPF9897 in  the QCPFMSG file  in QSYS.   This is a blank  message where
the text from the array is used as MSGDTA for the message.

No  second level text exists for  these standard messages, but multiple
messages may  be  sent  for the  same  error.   For  example,  the  Z11
message has several lines  of text.  Each line of message  text is sent
as a  separate message and would appear in  the subfile to help explain
the error.   Indenting  these  multiple line  messages may  assist  the
user in reading them.

Either or both of  the following approaches may be used  for your error

  **   Use the same  approach as shown in the  generated code.  Use U01
       - U99 as the message IDs to be placed in the ZZMCOD field.

     C                     MOVE 'Unn'     ZZMCOD           Msg code
     C                     EXSR ZZMSG                      Msg subr

       For  each error ID,  you must also  add the error  code and text
       for the message in the ZZA/ZZB arrays.

  **   Use message  IDs  that exist  in  a message  file.   This  would
       allow  you to have  second level  help for  a message  and would
       also  be  helpful  if  translation  to  different languages  was
       required.   Your code  should  enter the  message  file/library,
       message ID, and any replacement data such as:

     C                     MOVEL'msgfile 'ZZMSGF           Msg file
     C                     MOVEL'msgf lib'ZZMSGL           Msg file lib
     C                     MOVEL'msg ID'  ZZMSID           Msg ID
     C                     MOVEL'xxxxxxxx'ZZTMSG           Replace data
     C                     EXSR ZZMSG                      Msg subr

       Before each use  of the the ZZMSG subroutine, you  must fill the
       fields  with your  unique values.   The ZZMSG  subroutine resets
       the fields after sending a message as follows:

                   ZZMSGF   =   QCPFMSG
                   ZZMSGL   =   QSYS
                   ZZMSID   =   CPF9897
                   ZZTMSG   =   Blanks

Help text at run time

Standard help  text  is  provided which  describes  each  display,  the
options, function keys, etc.   The help text appears  in windows placed
over the  existing display.   All 'help' functions are  provided in the
DDS  by keywords  such as ALTHELP,  HLPARA, HLPRCD, and  HLPBDY (no RPG
code is involved with 'help text').

Either the HELP key or F1 invokes help.

Sample field help  exists for the  CODE field on  both the subfile  and
detail displays.  It is described in the UHCODE record format.

For each field  that you want to provide help text  for, use the HLPARA
and  HLPRCD  keywords.   For  example, the  first field  on  the ZZDSP1
record format has the following help keywords:

     A          H                           HLPARA(4 1  4 80)
     A                                      HLPRCD(UHCODE)

The HLPARA keyword defines the area  on the screen where the help  area
is defined.  Four parameters are required:

                Parameter 1 = Start line
                Parameter 2 = Start position
                Parameter 3 = End line
                Parameter 4 = End position

The HLPRCD parameter defines the help format to be displayed.

To  create  field help,  use  the  UHCODE  screen  as a  model.    This
provides one screen of help.

To  provide more  than one  screen of help  text for  a given  field or
section, see the ZZDUMY and  ZZDUMY20 screens as models (these  screens
do not appear during run time).

CRTSFLPGM escape messages you can monitor for

      TAA9891    Either the DSPF or RPG program failed to create

Escape messages from based on functions will be re-sent.

Generated program run time messages

There are no escape  messages sent from the generated  program intended
to  be  monitored  for.   Certain  disaster  situations  will cause  an
escape  message.  For  example, if you  have more entries  to be loaded
than can  exist  in the  array  or the  COD array  is  attempted to  be
loaded and the data is not in sequence.

CRTSFLPGM2 command parameters                         *CMD

   RPGMBR        The RPG  source member name  to be used which  is also
                 used  as  the object  name of  the  generated program.
                 Up to 10 characters may be entered.

                 The   member   and   program   must   not   exist   if
                 REPLACE(*NO) is specified.

   TITLE         The title  of the subfile program  to be created.   Up
                 to  30 characters may  be entered.   The title appears
                 at the top of the  generated displays and in the  text
                 of the members and objects created.

   OBJLIB        The library  where the  generated program and  display
                 file  will be  created.   The default  is *CURLIB.   A
                 specific library may be entered.

   TYPE          How the array data will be entered.

                 *COMPILE   is   the   default   meaning   that  source
                 statements exist in the  program for the compile  time
                 arrays.   The generated code will  include sample data
                 that  must be  modified for  your requirements.   Scan
                 the generated RPG source for ZZARRAYS and CODDSC.

                 *CALC may  be specified  to mean  the  data is  loaded
                 from a  file or  accessed from  an API,  a data  area,
                 etc.     The  TAASTDIQ  file  will   be  used  in  the
                 generated code  to produce  a  working program.    The
                 data  in the  file  is the  same  as in  the  *COMPILE
                 solution.   Source statements  must be changed  in the
                 RPG  source for  your requirements.   Scan  the source
                 repeatedly for CLCARR and make the changes.

   POSITION      A *YES/*NO value for  whether a 'Position to'  line is

                 *YES  is  the  default  to  provide  a  'Position  to'

                 *NO  may be specified  to eliminate  the 'Position to'
                 line.   Two additional  lines  appear in  the  subfile
                 using  this technique.   *NO  may be  meaningful if  a
                 single page or a few pages of entries exist.

   ALWSELECT     A  *YES/*NO  value for  whether  the user  may  make a
                 selection of one  of the  entries and  have the  value
                 passed back as a parameter.

                 *NO is  the default  meaning the  '1 = Select'  option
                 is not valid and does not appear on the display.

                 *YES  may  be  specified to  allow  the  '1 =  Select'
                 option.   The first option  '1' entered will cause the
                 generated program to  end and  returns the CODE  value
                 as  a   parameter.    Because  a   parameter  will  be
                 returned,  you must  call  the generated  program from
                 another program  and  pass a  parameter to  allow  the
                 return  of the  selected value.   If  no selection  is
                 made, *NONE is returned.

                 The  return  parameter is  defined  as  *CHAR LEN(10),
                 but may be changed.

   DSPFMBR       The DDS source member  name to be  used which is  also
                 used  as the  object  name  of the  generated  display

                 *DFT is  the default meaning that the  RPG member name
                 will  be used as  the name of  the display file source

                 If RPGTYPE(RPG)  is specified,  the display file  name
                 will be used  in the RPG F spec  and only 8 characters
                 may be entered.

                 The  member   and  display  file  must  not  exist  if
                 REPLACE(*NO) is specified.

   SRCLIB        The source  library  where  the  source  files  exist.
                 *LIBL is the default.

                 A specific library or *CURLIB may be specified.

   RPGTYPE       The type of  RPG source file to  be used.  RPG  is the
                 default.  RPGLE may be specified.

   TGTRLS        The  target release  of the RPG  program that  will be
                 created.    This  is  the   same  value  as  used   on
                 CRTRPGPGM or CRTBNDRPG  and is passed thru to  the CRT

                 *CURRENT  is  the default.    *PRV  may be  specified.
                 Use  the command prompter to  see the specific release
                 names that may also be entered.

   RPGSRCF       The RPG  source  file to  be used.    *RPGTYPE is  the
                 default meaning  to use the standard  source file name
                 based on the RPGTYPE parameter value.

                 With RPGTYPE(RPG), QRPGSRC is used.

                 With RPGTYPE(RPGLE), QRPGLESRC is used.

                 A specific name may also be entered.

   DSPFSRCF      The  DDS source file  to be used for  the DSPF source.
                 QDDSSRC is the default.

                 A specific name may also be entered.

   REPLACE       A  *YES/*NO  parameter  for  whether  the  source  and
                 object already exist.

                 *NO is  the default.   When *NO is  specified, neither
                 the  source  members  nor the  objects  to  be created
                 must exist.

                 *YES may  be  specified  to cause  a  replace  if  the
                 source members  and objects already  exist.   Only the
                 same  type of source  member and  same type  of object
                 will be replaced.

                 REPLACE(*YES)   is  useful  if   you  are  trying  the
                 different  options  to  help  determine  if  they  are

                 If you  replace the source, any changes  you have made
                 will  be  lost.    If you  have  made  changes  to the
                 source, you should copy  the existing members so  that
                 you can remake the changes.


  **   The data must be loaded in sequence into the COD array.

  **   The program  that is  created will  invoke TAA functions  during
       run time  which requires the TAA Productivity  Tools to exist on
       the system the program is called on.


The following TAA Tools must be on your system:

     ADJVAR          Adjust variable
     CHKAPOST        Check apostrophe
     CHKLIBL         Check library list
     CVTTIM          Convert time
     RTVDAT          Retrieve date
     RTVDBFA         Retrieve data base file attributes
     RTVVALA         Retrieve value attributes
     FILEFDBCK       File feedback
     HLRMVMSG        HLL Remove message
     SNDCOMPMSG      Send completion message
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message
     SNDSTSMSG       Send status message


The tool  is ready  to use.   The  generated program  and display  file
will need modifications.

Objects used by the tool

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

   CRTSFLPGM2    *CMD                   TAASTDI       QATTCMD
   TAASTDIC      *PGM       CLP         TAASTDIC      QATTCL
   TAASTDIR      *PGM       RPG         TAASTDIR      QATTRPG
   TAASTDIP      *FILE      PF          TAASTDIP      QATTDDS
   TAASTDIQ      *FILE      PF          TAASTDIQ      QATTDDS

The TAASTDIP  file contains source  used to  generate the display  file
and program.

The  TAASTDIQ  file  contains  the  array  data used  for  the  working
program if TYPE(*CALC) is used.

Added to TAA Productivity tools November 15, 2005

Home Page Up to Top