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
program.
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
CRTSFLPGM2'.
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
calculations.
-- 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)
TITLE('xxx')
OBJLIB(yyy)
SRCLIB(zzz)
-- 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
arrays.
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
*NO.
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
parameter.
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
*NONE.
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.
PGM
DCL &RTNCDE *CHAR LEN(8)
DSPFD FILE(xxx) TYPE(*MBRLIST) +
OUTPUT(*OUTFILE) OUTFILE(QTEMP/DSPFDP)
OVRDBF QAFDMBRL TOFILE(QTEMP/DSPFDP) SECURE(*YES)
CALL yyy PARM(&RTNCDE)
SNDPGMMSG MSG(&RTNCDE)
ENDPGM
CRTSFLPGM2 was specified with:
TITLE('Access Source Members')
TYPE(*CALC)
POSITION(*YES)
ALWSELECT(*YES)
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
ZZCOLHDS.
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
for.
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
subroutine.
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
arrays.
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
ZZDSP1Z1).
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
text:
** 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
required.
*YES is the default to provide a 'Position to'
prompt.
*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
file.
*DFT is the default meaning that the RPG member name
will be used as the name of the display file source
member.
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
command.
*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
required.
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.
Restrictions
------------
** 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.
Prerequisites
-------------
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
Implementation
--------------
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.
|
