The Create Subfile Program command creates a file maintenance program
which uses a subfile. A keyed file must be specified. Simple
validity checking, lower case, and edit codes may be specified. Both
display file and RPG program source are generated and then the
objects are created. You may need to modify the code to provide for
such things as advanced validity checking.
A second command RPLSFLPGM exists to allow a replace of the objects
if you modify the source. See the later discussion of the 'RPLSFLPGM
command' and how it differs from the CRTSFLPGM REPLACE(*YES)
function. See also the alternative section on 'Using the ARRLF
parameter'.
A typical subfile display would look like:
**********************************************************************
* *
* The Salesman List FILEA in LIBX SYSTEM1 *
* 12/04/09 10:15:00 *
* Pos to: State: IL City: Chicago *
* __ _____________ *
* *
* Type options, press Enter. *
* 2=Change 3=Copy 4=Delete 5=Display 7=Rename *
* *
* Opt State City Sales person Supervisor *
* _ IL Chicago Joe Smith Ed Jones *
* _ IL Highland Park Mary Brown Wilbur Wood *
* _ IL Western Springs Tom Thumb Ed Jones *
* _ . . . . *
* *
* F3=Exit F6=Add F7=Display file information F12=Cancel *
* *
**********************************************************************
The 'Position To' fields at the top would allow for changes to
re-position the subfile. The options are similar to any maintenance
display such as option '5 = Display' would display the entire record.
The F6 key would display a prompt screen to allow adding a new
record.
Either RPG or RPGLE source and object may be produced.
Not every file or field can be processed. See the later section on
'Restrictions'.
Getting started
---------------
** Determine the name of a simple keyed file that you would like
to try CRTSFLPGM on. Either a physical file or a logical file
with a single format may be used.
The name FILEA is used in the following discussion and has 2
key fields. Assume that all objects to be used exist in LIBX
which is on the library list and all objects created will also
exist in LIBX.
** Enter the CRTSFLPGM command:
CRTSFLPGM FILE(FILEA) TITLE('Subfile Pgm for FILEA')
** The CRTSFLPGM command uses the file definition to generate a
proposed layout for the 'position to' and subfile layout. The
sample layouts and a menu are displayed.
**********************************************************************
* *
* TAA Create Subfile Program - Menu FILEA in LIBX SYSTEM1 *
* 7/19/09 6:54:22 *
* --- Sample 'Position to' line --- *
* Pos to: State: xx City: xxxxxxxxxxxxxxx *
* *
* --- Sample Subfile Columns --- *
* Opt State City Sales person Sup... *
* x xx xxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxx xxx... *
* *
* *
* Select one of the following: *
* *
* 1. Create subfile program *
* 2. Change 'Position to' line *
* 3. Change Subfile line *
* 4. Change field options for Display/Change/Add *
* *
* Selection *
* ===> 1 *
* _ *
* *
* F1=Help F3=Exit F12=Cancel *
* *
**********************************************************************
** The 'position to' sample is made up of as many key fields as
fit on one line. In the example, there are only two key
fields and they fit.
The subfile columns are made up of the fields as defined in
the data base file for as many as fit.
The menu options 2-4 allow you to change the descriptive text,
re-design the subfile columns, and add field options. This
includes:
-- The 'position to' prompt text. Up to 15 characters may
be entered.
-- The subfile columns and headings. The fields that are
used for the column headings may be changed,
re-ordered, and revisions made to the column heading
text. The width of the column may also be increased to
allow a longer description or in preparation for using
a work field instead of the data base field. The same
layout will be used for the 'Confirm of Deletes'
display.
One line of column headings is standard. Space for 2
additional lines may be requested on CRTSFLPGM, but the
actual additional text must be entered by changing the
display file source. See the later section on
'Multiple lines of column heading'.
-- A change may be made to the detail descriptions that
appear on the Detail and Change/Add displays, validity
checking, the edit code to be used, and whether lower
case is needed. Validity checking includes whether a
character field is required (non-blank) and must not
have any blank characters. Other validity checking
allows simple comparisons (*NE, *GT ...), range
checking, a list of up to 16 valid entries, and date
checking.
See the later section on 'Sample displays and menu' for a more
detail discussion.
To help you understand the simplest use of CRTSFLPGM, just
take the defaults.
** When option 1 is used, the source would be generated and a
display file and program would be created in the object
library.
** By default the first QDDSSRC and QRPGSRC files found on the
library list would be used for the new source members. By
default, the display file name assigned would be the keyed
file name with a 'D' added at the end. Since the example uses
FILEA as the keyed file name, FILEAD would be used for the
DSPF source. The RPG name defaults to use the keyed file name
or FILEA in the example. The same names would be used for the
created display file and the RPG program. The spooled files
created by the CRT commands may be displayed.
** The SFLPGM spooled file is also output to provide a summary of
the results.
Use WRKSPLF to display the SFLPGM spooled file. The spooled
file describes the input parameters and the key fields that
exist in the file. Any errors are noted such as a field was
dropped or is too long to be considered in the subfile. Lines
are printed for whether the display file and the RPG program
have been successfully created.
** An escape message would be issued by CRTSFLPGM if either the
display file or the RPG program fail to create.
** A different escape message would occur if there are error
messages described in the listing (such as a field was
dropped).
** Call the generated program:
CALL PGM(FILEA)
The subfile would display the data from the FILEA file.
Typical options to work with the records are supported.
The generated display file and program
--------------------------------------
** The first member of the keyed file is opened. A different
member or file may be processed. See the section on 'Override
processing at run time'.
The file is processed by key and a second version of the same
file is processed by arrival sequence. The generated RPG code
uses the name TAASTDHA for the arrival sequence file, but the
file is overridden before it is opened to use the keyed file
name. The record format used for TAASTDHA is generated to be
the same as the keyed file.
** A 'display only' version is available by specifying
ALWCHG(*NO) on CRTSFLPGM. This provides the '5=Display'
option. No other options would exist nor the F6 key for
additions.
** The text that appears on the display for the 'Position to'
prompts, the subfile headings, and the detail field
descriptions use the following rules:
-- The column headings are used if they exist.
-- If no column headings exist, the field text description
is used.
-- If no column headings and no text description exists,
the field name is used.
The descriptions are truncated if they are too long. See the
section on 'Formatting rules'.
** The subfile display will contain as many of the fields from
the data base file as will fit. The order of the fields in
the data base file determines how they appear when the sample
is first displayed. Only fields that are 50 characters or
less will be considered for the columns of the subfile. The
sequence and column headings of the subfile may be changed
using Option 3 of the CRTSFLPGM menu. of CRTSFLPGM.
Data may not be changed on the subfile display. Use "Option 2
= Change" to change a record.
** "Position To" fields are generated at the top of the display
for as many key fields as fit on one line. Up to 15
characters of description may be entered. The colon is added
automatically.
The user may use these fields to re-position the subfile. If
the key fields specified do not exist, the subfile is
positioned to the record prior to the key specified.
A 'page at a time' subfile is used.
Rollup and rolldown from the 'positioned to' record is valid.
** A one line column heading is used for the subfile fields. See
the later section on 'Formatting rules' and 'Multiple lines of
column headings'.
** The PRINT key is valid on any display.
** A Detail display is generated for use by "Option 5 = Display".
Up to 20 screens of fields for the same record will be
generated. The Rollup and Rolldown keys are supported if
multiple screens exist.
The following is an example:
*********************************************************************
* *
* The Salesman List 1 of 1 *
* *
* State . . . . . . . . . : IL *
* City . . . . . . . . . : Chicago *
* Sales person . . . . . : Joe Smith *
* Supervisor . . . . . . : Ed Jones *
* Amount . . . . . . . . : .00 *
* *
* *
* F3=Exit F12=Cancel Press Enter to continue *
* *
*********************************************************************
One line on the screen is used for both the text and data for
each field that is 50 characters or less. Fields larger than
50 characters are provided for by using a standard first line
and then multiple lines of 80 characters per line. A maximum
of 15 lines per screen will be generated.
** A Change/Add display is generated for use by the "Option 2 =
Change" and "F6 = Add" functions. The design of the screen is
the same as for the "Option 5 = Display" function.
If Option 2 to Change a record occurs and the record is not
changed, no change occurs to the data base and a message is
sent describing that no change occurred.
When adding records, F18 may be used to duplicate the fields
from the previously added record.
** All display file fields use the REF DDS keyword and name the
specified keyed file. This causes the system to extract the
information stored with the file including the edit code and
any validity checking. If a decimal field does not have an
edit code specified, a 'J' edit code is used. You may specify
an edit code using Option 4 of the CRTSFLPGM menu.
Data Base DDS does not allow the specification of a field to
be keyed in lower case. A request for lower case entry may be
made using Option 4 of the CRTSFLPGM menu.
** A message subfile is used for the messages sent to the
subfile, Detail, and Change/Add displays.
** Special displays are created for "Option 3 = Copy" and "Option
7 = Rename". The prompts describe the existing and new key
fields to assist the user in entering the right values.
Note that a 'rename' may also occur by using "Option 2 =
Change" and changing the key fields. "Option 7 = Rename"
provides a simpler solution.
** Options are only displayed if the user is authorized. For
example, if the user has only *USE authority to the data base
files, only "Option 5 = Display" is valid. See the section on
'Security'.
** If the file has unique keys, a special display will appear if
a duplicate key is attempted to be added.
** When a 'change' option is requested, the appropriate record is
read without a lock and the original version is stored in the
program. This avoids locking the record for a long period of
time while the user makes a decision. When Enter is pressed,
the record is accessed again for update (causing a lock).
If the record lock is obtained and the versions agree, the
changes are made and the record is updated (releasing the
lock).
If the record lock is obtained and the versions differ (some
other job has updated the record between the two accesses), a
special display appears, the changes are discarded, and the
record is re-accessed (without a lock) to allow the user to
re-enter any changes.
If the record lock cannot be obtained, the TAA LOCKMSG display
appears informing the user. Several options exist such as
'retry' and 'send a message to the user who holds the lock'.
** If a field in the record is changed that appears in the
subfile, the subfile data is changed when it is re-displayed.
** If one or more "Option 4 = Delete" requests are made, a
"Confirmation" display appears and the user must confirm the
deletions.
If a record to be deleted is locked, a special display appears
and the delete request is rejected.
If the record to be deleted violates a 'referential integrity'
check, a special display appears and the delete request is
rejected.
** If a record appears in the subfile, it may be deleted by the
time the user attempts to perform an option. If so, a special
display appears.
** When a display file is created, the information (including
'position to' prompt text, the subfile field names and column
headings, field text, edit code, lower case, and validity
options) is stored as comments with the display file source.
This allows CRTSFLPGM (using REPLACE = *YES) to be used again
by starting with the same information. These special comments
should not be modified. See the later section on 'Storing
text in the display file source'.
** A keyed join file is supported, but must be ALWCHG(*NO).
** Any single quotes in text such as "O'Neil" are automatically
doubled in any of the text values to allow for the proper
presentation.
** Help text at run time is provided for the basic functions.
Individual field help text may be added. See the section on
'Help text'.
** The F7 key may be used at run time to display the following
menu:
*********************************************************************
* *
* The Salesman List *
* *
* Select one of the following: FILEA in LIBX *
* *
* 1. Display Keyed file format *
* 2. Display Keyed file attributes *
* 3. Display Keyed file access path *
* 4. Display Keyed file member description *
* 5. File Create/Open Comparison *
* 6. Program information *
* 7. Display file information *
* 8. Program validity checking information *
* *
* *
* Selection *
* ===> _ *
* *
* F3=Exit F12=Cancel *
* *
*********************************************************************
Options 1-4 allow for detail displays about the file, its
format, attributes, access path, and the member that was
opened.
Option 5 provides a comparison regarding the file specified
for CRTSFLPGM and the file actually opened.
Option 6 and 7 use the DSPOBJD2 TAA command to describe
information about the created objects.
Option 8 describes the validity checking that was specified
using CRTSFLPGM. DDS validity checking is not included.
CRTSFLPGM menu and displays
---------------------------
CRTSFLPGM begins by extracting information about the keyed file. If
REPLACE(*YES) is specified, the last source change dates from the RPG
and DDS source are extracted and compared against the source change
dates in the object. If they differ, an escape message is issued as
a re-create will cause a loss of the source changes. Use *YES2 to
replace or consider the RPLSFLPGM command.
If no changes have occurred and REPLACE(*YES) is specified, the
existing Display file source is read and the information from the
special comments is extracted.
As shown previously, the initial menu appears as:
**********************************************************************
* *
* TAA Create Subfile Program - Menu FILEA in LIBX SYSTEM1 *
* 7/19/09 6:54:22 *
* --- Sample 'Position to' line --- *
* Pos to: State: xx City: xxxxxxxxxxxxxxx *
* *
* --- Sample Subfile Columns --- *
* Opt State City Sales person Sup... *
* x xx xxxxxxxxxxxxxxx xxxxxxxxxxxxxxxxxxxxx xxx... *
* *
* *
* Select one of the following: *
* *
* 1. Create subfile program *
* 2. Change 'Position to' line *
* 3. Change Subfile line *
* 4. Change field options for Display/Change/Add *
* *
* Selection *
* ===> 1 *
* _ *
* *
* F1=Help F3=Exit F12=Cancel *
* *
**********************************************************************
The sample displays allow you to see the important layouts that will
be used. Menu options allow changes and access to field options.
If F3 or F12 is used to cancel from the menu, any existing objects
and source members remain as they were.
If the RPG or DSPF members do not exist prior to the use of
CRTSFLPGM, members are added before the samples are created. If F3
or F12 is used to cancel from the menu, the empty members are
removed.
The following describes each of the options that may be used for
making modifications:
** Option 2 - 'Position to' line.
*********************************************************************
* *
* TAA Create Subfile Program - 'Position To' Text Changes *
* *
* Type options, press Enter. *
* 5=Display *
* *
* Opt Key field Len Dec 'Position to' text *
* _ STATE 2 State *
* --------------- *
* _ CITY 15 City *
* --------------- *
* *
* F1=Help F3=Exit F5=Refresh F7=Display format ... *
* *
*********************************************************************
The order of the key fields of the file make up the 'position
to' line with a preceding text prompt for as many as fit on
one line. A colon is added after each text prompt.
The 'Position to' prompt text may be changed on the display.
Up to 15 characters may be entered.
After changing the text, the sample is re-displayed.
Increasing or decreasing the length of the text may cause a
different number of key fields to fit on the line.
** Option 3 - Change subfile line.
*********************************************************************
* *
* TAA Create Subfile Program - Subfile Column Changes *
* *
* Type options, press Enter. *
* 5=Display *
* *
* Opt Seq Field name MinWdth ColWdth HdgWdth Column hea *
* _ 010 STATE 6 6 5 State *
* --- -- ---------- *
* _ 020 CITY 15 15 4 City *
* --- -- ---------- *
* _ 030 SLSPER 20 20 12 Sales pers *
* --- -- ---------- *
* _ 040 MGR 20 20 12 Supervis.. *
* --- -- ---------- *
* - AMT 9 9 6 Amount *
* --- -- ---------- *
* *
* F1=Help F3=Exit F5=Refresh F12=Cancel *
* *
*********************************************************************
The 'Seq' column describes which fields will be displayed in
the subfile. All fields in the file are displayed, but only
those being used in the subfile will have a sequence number.
Blanking out the sequence number causes the field to be
removed as a column. You may add new fields or re-arrange the
order of the fields by changing the sequence numbers.
For example, the AMT field exists in the file, but is not used
on the subfile display because there is insufficient room.
You could blank out the sequence of MGR and enter a sequence
number for AMT to rearrange the subfile.
-- The 'MinWdth' column describes the minimum width of the
column. See the section on 'Formatting rules' for a
discussion of the minimum width.
-- The 'ColWdth' field defaults to the size of the minimum
width, but allows you to increase the size. For
example, you could make a longer column heading or in
preparation of a manual change to the generated source
where you need to translate a code into descriptive
text. See the later section on 'Translating a code to
a descriptive literal'. You cannot decrease the size
of the column width to be less than the minimum width.
-- The 'HdgWdth' column describes the length of the
proposed column heading. This is always the last line
of column headings. See the section on 'Multiple lines
of column headings'. This allows you to compare
against the 'ColWdth' information to see if the column
heading text can be increased in length.
-- The 'Column heading' information describes the proposed
text for the column. You may change the text, but you
may not make it longer than the 'ColWdth' size. If the
text is changed to be longer, it will be truncated to
the column width and a message sent.
Increasing the column widths may cause fewer columns to appear
when you return to the sample display.
** Option 4 - Change Field Options
*********************************************************************
* *
* TAA Create Subfile Program - Change Field Options *
* *
* Type options, press Enter: *
* 2=Validity checking 5=Display *
* *
* Opt Field name Typ Len Dec Vld Rqd Ful Lwr Edt Detail/Ch *
* _ STATE A 2 X State *
* - - - --------- *
* _ CITY A 15 City *
* - - - --------- *
* _ SLSPER A 20 Sales per *
* - - - --------- *
* _ MGR A 20 Superviso *
* - - - --------- *
* _ AMT P 7 2 J Amount *
* - --------- *
* *
* F1=Help F3=Exit F5=Refresh F7=Display format F1 *
* *
*********************************************************************
Using option 4 will allow you to make changes to the text
description that will be displayed on the Detail/Change/Add
displays and enter various field level options.
Columns for 'type', 'length', and 'number of decimal
positions' are shown for each field. The type is from the
system code used for the field. A=Alphameric, but is
described as 'character' in this discussion. The decimal
fields are either P=Packed, S=Zoned, or B=Binary.
'Vld' column. The 'Validity' column will be set to X if you
have used Option 2 and specified validity checking for the
field. See the next section on 'Validity checking'.
'Rqd' column. The 'Required' column is valid for character
fields. Entering an X will cause the program to ensure that
any data entered into the field is non-blank. By default, the
first key field is required (this can be changed). Decimal
fields will be initialized to zero so a value always exists.
You can require a value greater than zero by using validity
checking (see the section on 'Validity checking).
'Ful' column. The 'Full' column is valid for character fields
(the system code shown is A = Alphameric). Entering an X will
cause the program to ensure that all characters entered into
the field are non-blank. This would be a good option for the
STATE field (always 2 characters), but not for the CITY,
SLSPER, and MGR fields. Requesting 'Ful' requires the field
to be entered as does a 'Rqd' request. Requesting both 'Rqd'
and 'Ful' may appear redundant, but a different error message
will appear when using 'Rqd' when the field is all blank that
may be more understandable to the end user.
'Lwr' column. The 'Lower case' column is valid for character
fields. Entering an X will allow the entry of lower case into
the field. This would not be used for the STATE field, but
would be a good option for the CITY, SLSPER, and MGR fields.
'Edt' column. The 'Edit code' column is valid for decimal
fields. The value used from the Data Base DDS is the default.
If none exists, J is used. Any of the standard editing codes
may be used. The edit code is used anytime the field is
displayed. This includes the Detail and Change/Add displays,
'Position to' line, the subfile line, and the copy/rename
prompts. The Y edit code may only be used on a digit length
of 3 to 8 with 0 decimal positions.
'Detail/Chg/Add text' column describes the text that will be
used on both the Detail display and the Change/Add displays.
Up to 23 characters may be displayed. If the field text is
longer than 23, it is truncated. You may want to change some
of the text to make it more understandable.
Option 2 may be entered for Validity Checking (see the section
on 'Validity Checking'.
Option 5 will provide a display of the detail attributes of
the field.
To do the 'Salesman List' sample, the following would be the
typical entries:
*********************************************************************
* *
* TAA Create Subfile Program - Change Field Options *
* *
* Type options, press Enter: *
* 2=Validity checking 5=Display *
* *
* Opt Field name Typ Len Dec Vld Rqd Ful Lwr Edt Detail/Ch *
* _ STATE A 2 X X State *
* - - - --------- *
* _ CITY A 15 X X City *
* - - - --------- *
* _ SLSPER A 20 X X Sales per *
* - - - --------- *
* _ MGR A 20 X X Superviso *
* - - - --------- *
* _ AMT P 7 2 J Amount *
* - --------- *
* *
* F1=Help F3=Exit F5=Refresh F7=Display format F1 *
* *
*********************************************************************
The STATE field is specified as 'Rqd' and 'Ful' meaning a 2 character
non-blank entry is required.
The CITY, SLSPER, and MGR fields are specified a 'Rqd' and 'Lwr'
meaning a value must be entered, but lower case is allowed.
Validity checking
-----------------
Simple validity checking may be requested. The 'Rqd' and 'Ful'
fields on the 'Change Field Options' display provide some simple
checking for character fields.
Additional validity checking may be requested by using 'Option 2 -
Validity checking'. This option is only valid on character or
decimal field types.
Assume you used option 2 for the AMT field.
*********************************************************************
* *
* TAA Create Subfile Program - Validity Checking for Field AMT *
* *
* Type . . *PACKED Length . . 7 Dec Pos . . 2 *
* Text . . Amount *
* Enter one type: *
* Comp: Oper __ Value ________________ *
* *
* Range: Low ________________ High ________________ *
* *
* List: 1 ________________ 2 ________________ *
* 3 ________________ 4 ________________ *
* 5 ________________ 6 ________________ *
* 7 ________________ 8 ________________ *
* 9 ________________ 10 ________________ *
* 11 ________________ 12 ________________ *
* 13 ________________ 14 ________________ *
* 15 ________________ 16 ________________ *
* *
* Date: Fmt ________ Sep _ *
* Low -99999 High 99999 *
* ------ ------ *
* *
* F1=Help F3=Exit F5=Refresh F7=Display format F1 *
* *
*********************************************************************
One of the 4 validity checking types may be entered for each field.
When entering data for a character comparison, the data should be
left justified without surrounding quotes. The length of the data
entered cannot exceed the length of the field being compared.
Note that if a character field is not set for 'Required' or 'Full' on
the Change Field Options display, a blank value will not be checked
by one of the types entered. For example, if a character value must
always exist and be within a range of values, you must enter both an
'X' for Required and the range values.
When entering data for a decimal comparison:
- Use digits 0-9 and an optional leading minus sign.
- No embedded blanks may exist.
- No decimal point character may exist (for 10.00 enter 1000).
- The length may not exceed the digit length of the field.
- The data may be entered left or right adjusted.
If the data is re-displayed, it will be right adjusted
** Compare type. An operator *EQ, *NE, *GT, *GE, *LT, *LE and a
single value to compare to must be entered.
For example, if the AMT field must be greater than 0, you
would enter *GT 0.
** Range type. A low and a high range may be entered for either
character or decimal fields.
For example, if the AMT field must be greater than zero and no
larger than 9999.99, you would enter Low = 1 and High =
999999. Note that the decimal values are entered without
decimal points.
** List type. A list of up to 16 values for either character or
decimal fields. The values may be entered in any order. Any
blank entries are ignored. If re-displayed, the non-blank
entries will begin with the first list entry.
** Date type. If the field to be entered is a date type, you may
enter one of the standard formats *MDY, *DMY, *YMD, *MDYY,
*DMYY, *YYMD, *CYMD, *JUL, *LONGJUL, *ISO, *USA, *EUR, or
*JIS. The field may be either character or decimal.
If a character date field is to be checked, you must enter a
separator character if it exists. A separator character is
not valid for decimal fields.
The length of the field must conform to what was entered. For
example, an *MDY formatted field must be either a 6 byte
character or 6 digit decimal field. If a separator is
entered, the field must be character of length 8.
Date checking ensures that the data entered as a date value is
meaningful. For example, you cannot request a month 13 or day
32. Feb 29th is checked for leap years.
The value entered may be checked for a low or high date. The
low and high values default to -99999 and 99999 thus allowing
a large range of dates to be entered.
If you consider entering a date prior to the current date an
error, use 0 for the low value. If you consider any date
prior to 10 days in the past of the current date to be
invalid, enter -10 for the low value. If you consider any
date in the future to be invalid if it is greater than 700
days from the current date, enter 700 for high value.
Formatting rules
----------------
** The text that appears on the display for the 'Position to'
prompts, the subfile headings, and the detail field
descriptions use the following rules:
-- The column heading information is used if it exists.
If multiple column headings exist such as the physical
file DDS is specified as:
COLHDG('Sales' 'person' 'name')
the 3 values are concatenated together with intervening
spaces and the text would be 'Sales person name'. See
the later section on 'Multiple lines of column
headings'.
-- If no column heading exists, the field text description
is used.
-- If no column heading and no text description exists,
the field name is used.
The descriptions are truncated if they are too long. You may
modify any of the text descriptions.
Position to
-----------
** The text prompt is limited to a maximum of 15 characters. A
shorter prompt may be desirable to allow more key fields to
appear on the 'Position to' line. Two ellipsis are added
automatically.
Subfile
-------
** The column width determines the length of the column text that
will be used.
** The column widths have a minimum of 3 characters. The minimum
width will be longer if:
-- For character fields, the field length is longer.
-- For decimal fields, the edited length of the field is
longer. The edited length includes the digit length,
room for a decimal point (if decimal positions exist),
and room for separator characters (eg commas),
depending on the length and edit code used. If a
decimal field does not have an edit code, J is assumed.
If a Y edit code is used, room for the separators is
added to the digit length. You may specify the edit
code to be used for any decimal field.
** By default, there are 3 spaces between the columns. You may
specify the number of spaces with the SPACING parameter. An
extra space is added if an edit code A-D is used to allow
additional space for the 'CR' symbol.
** For decimal fields, the column heading is right adjusted to
the units position.
** For character fields, the column heading is normally left
adjusted to the start of the data. If the data is shorter
than the column heading, the data is centered under the column
heading.
** Changing the edit code of a decimal field may cause a
difference in the column width.
Detail and Change/Add Displays
------------------------------
** There is room for a 23 characters of description.
Storing text in the display file source
---------------------------------------
When display file source is generated, special comments are placed at
the end of the source with appropriate leading and trailing
information. The comments describe what was specified to create the
display file. This includes the text used for 1) the 'position to'
fields, 2) the sequence, column width, and column headings for the
subfile, and 3) the descriptive text for the Detail and Change/Add
displays.
In addition, the edit code and validity checking information are also
stored in the special comments.
This information is used if CRTSFLPGM with REPLACE(*YES) or
REPLACE(*YES2) is specified for the same display file name. This
allows CRTSFLPGM to begin with the information as was used in the
last created version.
These special comments should not be modified.
If the display file source was not used for the same file name that
is currently specified, any existing information in the source is
discarded.
Array data in the created RPG program
-------------------------------------
Compile time arrays are used in the RPG program for error messages
and validity checking information.
Security
--------
** The user of CRTSFLPGM must have at least *USE authority to the
file specified as well as the CRT commands used.
** The user who calls the generated program must have at least
*USE authority to the file that is opened. If not (such as
the user is *EXCLUDE), the system issues CPF4104 as an escape
message when the open is attempted.
Because an OVR may occur, the created program cannot tell
ahead of time what file will be opened and the check occurs
when the file is first opened.
** If the file is specified as ALWUPD(*NO), ALWWRT(*NO), or
ALWDLT(*NO), these options are honored regardless of what
authority the user has to the file. Messages appear on the
first display of the subfile informing the user.
** Most authority to objects is set for *PUBLIC or individual
users as *USE or *CHANGE.
*USE authority would allow only the '5 = Display' option to
appear. The other options (and F6 for 'add') would not
display and would cause an error if entered.
*CHANGE authority will allow all of the options and F6 for add
of a new record.
If individual rights exist for the user such that 'USER DEF'
is displayed by DSPOBJAUT, the following would occur:
-- If the user does not have *DLT authority, the Delete
option would not appear.
-- If the user does not have *UPD authority, the Change
and Rename options would not appear.
-- If the user does not have *ADD authority, the Copy
option and the F6 key (for Additions) would not appear.
Generated source TAA identification
-----------------------------------
The generated DSPF and RPG source will contain the letters ' TAA ' 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.
Assume you have some additions for more advanced validity checking
and your source statements were entered with blanks for the leading 5
characters. If you want to refresh using CRTSFLPGM, do the
following:
** Copy your existing source to separate members.
** Use CRTSFLPGM with REPLACE(*YES) which will replace the
existing DSPF and RPG source. If any changes have occurred to
either the RPG or DDS source, an escape message will be
issued. Use REPLACE(*YES2) or consider the use of RPLSFLPGM.
** Use SEU on the newly generated source.
** Use F15 (Browse/Copy Option) and display the previous source.
** Use F14 (Find/Change Option) on the previous source.
** Specify 5 blanks for Find and scan columns 1 to 5 as:
Find . . . . . . . . ' '
From column number . 1
To column number . 5
** Return to the main SEU display.
** Use the F16 key to scan for your statements.
** Copy from the previous source to the newly generated source.
Modifying the generated source
------------------------------
You may want to modify the generated source for such changes as:
** Adding advanced validity checking.
** Shortening a descriptive field to make it fit in the subfile.
** Changing a code into a descriptive text.
After making the source code changes, the RPLSFLPGM command exists to
replace the existing objects. Do not use CRTSFLPGM again as this
will delete your changes. The direct use of a CRTrpg command will
fail because the TAASTDHA file does not exist (an OVR command is
needed). See the later discussion of the 'RPLSFLPGM command'. See
also the alternative section on 'Using the ARRLF parameter'.
Certain field names and indicators are standard and should not be
used when you make changes. Any conflict with the names or
indicators required by your display file and program function will
probably produce unexpected results.
** Indicators 61 - 99 are used for internal control and for
display file options. Indicators 21-60 are used for validity
checking. Up to 40 fields may be checked which will be
highlighted. The first field to be validity checked uses
indicator 21, the second field indicator 22 and so on. These
indicators are used to highlight the error fields and position
the cursor to the error.
If you have less than 40 fields to be used for validity
checking, you may safely use the remaining indicators. Good
practice would be to use 60 and work down.
If you need more indicators you could consider L0-L9 (the
generated program does not use the RPG cycle) or KA-KN and
KP-KY.
** Field names beginning with ZK, ZX, and ZZ are used for
internal control and display file options. Formats beginning
with ZH are used in the display file for help text.
** Field names beginning with FD and FI are created by the use of
the TAA FILEFDBCK tool which uses an externally described data
structure for the file feedback area.
** Field names beginning with ST are created by the use of the
TAA RPGSTSDS tool which uses an externally described data
structure for the RPG status data structure.
** Field names beginning with DT are created by the use of the
TAA CHKDAT3 tool which uses an externally described data
structure for communication with the RPG program.
At the beginning of the DDS and RPG code are comments that are
designed to assist in determining where typical changes need to
occur.
The following sections describe some typical changes you may want to
make and tips on where to modify the source:
** Changing the 'Position to' prompts
** Changing column headings
** Multiple lines of column headings
** Changing the field text for the Detail and Change/Add
displays.
** Shortening a field for the subfile display
** Translating a code to a descriptive literal.
** Initializing a value before prompting for a new record
** Advanced Validity checking
** Bypassing records that should not be in the subfile
** Displaying messages
** Help text at run time
Changing the 'Position to' prompts
----------------------------------
The typical means of changing the 'position to' prompt text would be
using menu option 2 that appears during the use of CRTSFLPGM.
You may also change the text in the DDS source (eg making it more
than 15 characters).
To change the text, scan the DDS source for ZZPOSTO and key over the
existing value. You may need to adjust the positions.
Changing column headings
------------------------
The typical means of changing the column heading text would be using
menu option 3 that appears during the use of CRTSFLPGM.
You may also change the headings by modifying the display file
source.
Column headings appear in the DDS subfile display and in the screen
for confirming deletions. There is one line of column headings if
the default of COLHDG(1) is used. See the section on 'Multiple lines
of column headings'.
If the DDS field text value is too long, the text is truncated. Very
short fields make use of the field name.
To make a different column heading, scan for ZZCOLHDS which begins
the section. Key over the existing column heading and adjust the
position if needed.
Scan again for ZZCOLHDS and change the column heading in the
confirmation of deletions.
You may make a two line column heading if needed.
-- Scan for ZZOPTL in the display file to see the
beginnings of the column headings which begin on line
8. Your second line of column headings should begin on
line 9.
-- Scan for ZZSFL2C in the display source to make the
column headings for the 'Confirm Delete' display.
Those column headings begin on line 6 as there is no
'Position to' line.
-- Scan the display file source for SFLSIZ and change the
number 12 to 11 if you have 2 lines of column heading.
Make the same change to the SFLPAG keyword.
-- Scan the RPG source for ZZFULP and change from 12 to 11
if you have 2 lines of column heading.
Multiple lines of column headings
---------------------------------
The default is COLHDG(1) for one line of column headings.
A value of 2 or 3 may be specified in which case the screen is
formatted to allow 2 or 3 lines, but the only set of column headings
generated by CRTSFLPGM in for the last line. After the display file
has been created and you are satisfied with the layouts and text
descriptions, use a source editor for the display file source and
scan for ZZCOLHDS. Add the required display file specifications for
the main subfile.
A second scan for ZZCOLHDS should be used for the 'Confirm Delete of
Records'. The same set of column headings may be used as on the main
subfile, but the line number values should be changed.
Changing the field text for the Detail and Change/Add displays
--------------------------------------------------------------
The typical means of changing the field text descriptions would be
using menu option 4 that appears during the use of CRTSFLPGM.
The field descriptions appear on the DDS Display of a record and the
Change/Add display. If the description to be changed is for a key
field, other displays (such as the Copy prompt) also use the
description. There is room for 23 characters of description.
To change the text, scan for the DDS source for ZZFLDTXT and key over
the existing value.
Keep scanning for ZZFLDTXT until all changes have been made.
Shortening a field for the subfile display
------------------------------------------
In some cases there may not be enough room on the subfile display for
the full length of a character field that provides a description.
You can shorten the field and display the shorter value.
For example, assume you have a few important fields and a 50
character description that you want to display in the subfile. There
may not be enough room for all 50 characters of the description, but
it would be helpful if the first 30 were displayed.
Do the following:
** DDS changes
-- Scan the DDS source for ZZSFLRCD and add the required
field to the subfile display ZZSFL1.
-- Scan the DDS source for ZZDLTRCD and add the required
field to the subfile display ZZSFL2.
-- Scan the DDS source for ZZCOLHDS and add the column
heading for the subfile control display ZZSFL1C.
-- Scan the DDS source again for ZZCOLHDS to add the
column heading for the confirmation of deletions
display ZZSFL2C.
** RPG changes
-- Scan the RPG source for ZZCVTFLD. This is the ZZCVT
subroutine which is used to change any fields in the
subfile before it is displayed. The subroutine is
called any time the fields are built for the subfile or
the confirmation of deletions. Use a MOVEL or EVAL to
move from the data base field to the field you defined
in DDS.
Translating a code to a descriptive literal
-------------------------------------------
If your data base field is a code that may not be known to the end
user, you may want to display descriptive text instead of the code.
For example, if 'I' is 'Income', you may want to display 'Income'
rather than the 'I'. If the field is in the subfile display, the
technique would be similar to that described for 'Shortening a field
for the subfile display'. You would have to use a work field on the
display instead of the actual data base field.
To change a field on a detail display of a record, you will need to
change the DDS for a different field name. Scan the DDS source for
ZZFLDTXT and make the required change. Scan again for ZZFLDTXT and
make the required change for the Change/Add display.
Then scan the RPG source for ZZFXBFR and insert any changes. The
ZZFXB subroutine is invoked before displaying a record for either the
Display or Change screen.
The ZZFXA subroutine is invoked after the user has changed a record
and before it is written to the data base. Scan for ZZFXAFT and
insert any changes from what the user has keyed to what is required
in the data base.
Initializing a value before prompting for a new record
------------------------------------------------------
By default, a prompt for a new record will display values as zeros
and blanks. You may want to initialize certain fields before
prompting. If so, scan the RPG source for ZZNEWRCD. This will
display the ZZNWB subroutine and allow entry of your statements to
initialize certain fields.
Advanced Validity checking
--------------------------
Most simple validity checking may be added using option 4 from the
CRTSFLPGM menu and Option 2 from the subsequent display. This
provides checking for required fields, making simple comparisons, and
ensuring valid dates.
The system also supports some validity checking:
** If your DDS for the file has keywords such as COMP, RANGE, or
VALUES, the keywords will have been copied to the generated
DDS. The system will ensure that any changes or new data must
pass the validity checking.
** If an error is detected, the fields in error are reverse
imaged, the cursor is positioned to the first field in error,
the keyboard is locked, and an error message will be
displayed. The RPG program will not gain control until the
validity checking has been passed.
Adding advanced validity checking may include such functions as:
** Accessing a data base file to verify a key.
** Providing a large array of valid entries (the LIST function
allows for only 16 entries. You are probably better off to
add your own array data and error handling. You can extend
the ZZF and ZZV arrays, but you must follow the same pattern
with the Field name in 1-10 and the Type/Value in 11-26.
** Validity checking involving multiple fields. For example, if
a customer is a type XX, he may not have a discount code which
is in another field.
You can provide your own validity checking by placing code in the
ZZVAL subroutine. It is invoked after the user has entered values on
the Change/Add display. Scan for ZZVALSBR to find the subroutine.
If an error has occurred and you want to re-prompt the user, set
ZZVALE to *ON as shown in a later example.
See the 'Messages' section on how to send a message explaining the
error.
If you want to emulate the system validity checking by reverse
imaging the field and positioning the cursor, you need to modify the
DDS. Scan the DDS source for ZZCHG which is the beginning of the
Change/Add displays. Add the DSPATR keyword after the field and
condition by an indicator such as 19 (see the comments about which
indicators may be used in the section on 'Modifying the source').
A OPTION R B +3REFFLD(OPTION xxxx )
A 19 DSPATR(RI PC)
This technique does not lock the keyboard.
You should reset any indicators you are using for validity checking
in the ZZRST subroutine. Scan the RPG source for ZZRSTSBR and enter
a SETOF operation for each such indicator you are using for validity
checking.
C SETOF 19 Reset
Note that the ZZRST subroutine is already setting validity checking
indicators off.
The following code describes what could be done to validate a field
named OPTION for a value of *YES or *NO. This simple type of
checking would normally be done by the validity checking LIST
function of CRTSFLPGM, but provides a good example.
Assume you have made the above DDS changes for the field with
indicator 19 and the change to the ZZRST subroutine. Assume you have
added an error message for U22 as described in the section on
'Messages'.
C SELEC Select
C OPTION WHEQ '*YES' If *YES
C OPTION WHEQ '*NO ' If *NO
C OTHER Other
C SETON 19 Set RI PC
C MOVE *ON ZZVALE Re-display
C MOVE 'U22' ZZMCOD Set code
C EXSR ZZMSG Error subr
C ENDSL End select
If only a single Change/Add screen exists, there is no confusion
between what the user sees and what the program has processed.
If the file has more fields than fit on one display, multiple ZZCHGnn
screens will exist. You may need to know which screen the user is
operating on. The field ZZFMT will contain the format name of the
last screen that appeared using rollup.
Bypassing records that should not be in the subfile
---------------------------------------------------
If you want to bypass certain records that should not appear in the
subfile, scan for ZZBYPASS. Use a GOTO ZZREAD to bypass.
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 Z03
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.
See the example in the 'Validity checking' section for how the
following two statements can be used to send a message.
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 first field on several displays. It
is described in the ZZFLDHLP 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 ZZDSP01
record format has the following help keywords:
A H HLPARA(4 1 4 80)
A HLPRCD(ZZFLDHLP)
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 ZZFLDHLP 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).
Override processing at run time
-------------------------------
You may use your own OVRDBF command prior to calling the RPG program.
You could process a different file or a member other than the first
member of the file.
If the file you are overriding to is specified as LVLCHK(*NO), the
program still ensures that the format IDs are the same as the file it
was created for.
RPLSFLPGM command
-----------------
If you only use CRTSFLPGM to make changes, you do not need RPLSFLPGM.
The RPLSFLPGM command is intended to re-create the objects if you
have made source changes using a source editor. By default, both the
display file and the RPG program are re-created by the use of
RPLSFLPGM.
The CRTSFLPGM REPLACE(*YES) or REPLACE(*YES2) function differs from
RPLSFLPGM. When CRTSFLPGM runs, the menu allows you to make changes
to text, re-order the subfile columns, etc. These changes are
captured in the display file source. When REPLACE(*YES) or
REPLACE(*YES2) is specified, CRTSFLPGM uses the values that were
found in the source. When Option 1 is used from the menu to create
the display file and program, the existing source is cleared and
re-generated.
REPLACE(*YES) will cause an escape message if any source changes have
been made to either the DDS or RPG source.
REPLACE(*YES2) will re-create the objects, but any source changes you
had made would be lost.
RPLSFLPGM does not re-generate the source. It uses the existing
source (including any changes you may have made) and re-creates the
display file and program.
The RPLSFLPGM command has most of the same parameters as on
CRTSFLPGM.
The command has the following advantages:
** After making source changes, you can duplicate the CRTSFLPGM
command, change the verb to RPL, and prompt. The missing
parameters will be dropped and you can re-create the objects
without the individual use of the CRT commands.
** The direct use of CRTRPGPGM will fail because the TAASTDHA
file does not exist. An OVRDBF command is needed prior to
creating the program that directs TAASTDHA to your keyed file.
RPLSFLPGM does the override automatically.
RPLSFLPGM also does a good deal of checking to ensure that the object
and source are the same as was specified on CRTSFLPGM.
The DDS source can be changed and created normally with the CRTDSPF
command. An option exists on RPLSFLPGM to bypass the create of the
display file by use of DSPFMBR(*NONE).
For an alternative to the use of RPLSFLPGM, see the section on 'Using
the ARRLF parameter'.
Creating the objects using CRTDSPF and CRTRPG commands
------------------------------------------------------
If you need specific parameter options provided by CRTDSPF or one of
the RPG create commands, the following should be considered:
** No exceptions exist for CRTDSPF. Just use the normal CRTDSPF
command.
** The RPG program opens the dummy TAASTDHA file as an arrival
sequence file. Prior to opening the file, the TAASTDHA dummy
file is overridden to the keyed file. If you create the
program using a CRTrpg command, you must first use an OVRDBF
command. An alternative exists that allows a second real
file. See the section on 'Using the ARRLF parameter'.
If you use the override technique, you must override the
TAASTDHA file to your keyed file such as:
OVRDBF FILE(TAASTDHA) TOFILE(xxx)
CRTrpg ...
Using the ARRLF parameter
-------------------------
An alternative to using RPLSFLPGM, is to use CRTSFLPGM ARRLF
parameter and name an arrival sequence LF built over the keyed file
specified for the FILE parameter. The arrival sequence file must
exist. This causes the generated code to use the ARRLF file and
allows both the display file and the RPG program to be created
normally (no OVR command is needed).
CRTSFLPGM escape messages you can monitor for
---------------------------------------------
TAA9891 Either the DSPF or RPG program failed to create
TAA9892 The DSPF and RPG program created, but some
errors were found (eg fields dropped)
Escape messages from based on functions will be re-sent.
Program run time messages
-------------------------
There are no escape messages sent from the program intended to be
monitored for. Certain disaster situations may cause a unique
display or send an escape message.
CRTSFLPGM command parameters *CMD
----------------------------
FILE The qualified name of a keyed file to be used. A
maximum of 5 key fields may exist. The maximum key
length of any one key field cannot exceed 50 bytes.
Either a physical file or a logical file with a
single format may be specified.
The library qualifier defaults to *LIBL. *CURLIB or
a specific library may be entered.
Because the file name will be used in the REF
keyword of the generated DDS, the file must exist on
the library list when CRTSFLPGM is used.
If RPGTYPE(RPG) is used, the file name must be 8
characters or less.
TITLE The title of the subfile program to be created. The
default is *RPGSRCMBR meaning to take the value from
the RPG source member. If the member does not
exist, an escape message is sent.
The first time an RPG member is created, the
standard text '-Subfile Program' is added to the
TITLE value as a text description on the RPG and DDS
source. If *RPGSRCMBR is specified and the RPG
member exists with text that ends with the standard
text, it is stripped off for the title of the
displays.
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.
ALWCHG A *YES/*NO value for whether changes will be allowed
even if the user is authorized.
*YES is the default to allow changes if the user is
authorized.
*NO may be specified to make '5=Display' the only
option. This makes the subfile program an inquiry
program.
*NO must be used for a joined file.
COLHDG The number of column heading lines that should be
provided for.
The default is 1.
An entry of 2 or 3 may be specified in which case
the screen layout will allow for what was requested,
but the only text descriptions provided will be for
the last line. After the display file has been
created and you are satisfied with the layouts and
text descriptions, use a source editor for the
display file source, scan for ZZCOLHDS, and add the
additional column heading lines.
SPACING The number of spaces between subfile columns. The
default is 3. A number between 1 and 9 may be
specified. A subfile column width is determined by
the width of the field (minimum of 3) and any
additional characters required for editing.
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.
*DFT is the default meaning that the data base file
name is used.
The member and program must not exist unless
REPLACE(*YES) or REPLACE(*YES2) is specified.
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 data base file
name is used followed by a D. For example, if the
data base file name is ABCD, the DDS member and
object name will be ABCDD.
If RPGTYPE(RPG) is specified, the display file name
will be used in the RPG F spec and only 8 characters
may be entered. This requires the data base file
name to be 7 characters or less if *DFT is used.
The member and display file must not exist unless
REPLACE(*YES) or REPLACE(*YES2) 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/*YES2/*NO parameter that determines whether
the source members and objects may already exist.
*NO is the default meaning the members and object
names must not exist. An escape message will occur
if they do.
If *YES is specified, the date/time of the last
source change of the members are checked against the
corresponding date/time in the RPG and display file
objects.
If the date/time values are the same, no source code
changes have occurred. New source statements are
generated and replace the existing source. The
objects are re-created. If the objects do not
exist, they are created.
If the date/time values differ from either object,
an escape message is issued warning you that any
source changes will be lost. You should specify
REPLACE(*YES2) or consider the use of RPLSFLPGM.
*YES/*YES2 are intended for such situations where
you have used CRTSFLPGM and after reviewing the
results, you decide to make a change using the menu
that appears during CRTSFLPGM.
For example, you may decide to re-arrange the
columns in the subfile or make different column
headings or detail field descriptive text.
Because the display file source contains comments
about your original design, you can pick up where
you left off without having to make the same changes
again.
If the display file source was not created for the
file that was named, any existing stored information
is discarded.
A *YES is rejected if the members to be replaced are
not RPG or DSPF types. A *YES is also rejected if
the objects to be deleted do not have RPG or DSPF
attributes.
The *YES2 option is available if you have made
source changes, but want to start over. *YES2
starts over based on the special comments in the DDS
source. Any changes you have made to either the RPG
or DDS source will be discarded.
See the RPLSFLPGM command to re-create the objects
without re-generating the source.
If you need to re-use CRTSFLPGM after making source
changes, you should copy your original source
members to allow any changes you have made to be
re-incorporated and then specify REPLACE((*YES2).
If the format of the file has changed, you may use
CRTSFLPGM again to incorporate the changes. If you
have made changes to the generated source, you
should copy your original source members first.
ARRLF An arrival sequence logical file may be named
instead of using a second open of the keyed file.
This approach should be considered if you are
planning many source changes and re-compiles of the
RPG program.
ARRLF Creating an arrival sequence logical file avoids the
use of RPLSFLPGM and the requirement for running an
OVR command prior to creating the RPG program.
Naming an arrival sequence logical file allows the
direct use of the RPG created commands or by use of
WRKMBRPDM.
If a file is named, it must be an arrival sequence logical file with
the same format as the keyed file and in the same library as the
keyed file.
RPLSFLPGM command parameters *CMD
----------------------------
FILE The qualified name of the keyed file that was
specified on CRTSFLPGM.
The library qualifier defaults to *LIBL. *CURLIB or
a specific library may be entered.
Because the file name will be used in the REF
keyword of the generated DDS, the file must exist on
the library list when CRTSFLPGM is used.
If RPGTYPE(RPG) is used, the file name must be 8
characters or less.
OBJLIB The library where the generated program and display
file will be created. The default is *CURLIB. A
specific library may be entered.
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.
*DFT is the default meaning that the data base file
name is used.
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 data base file
name is used followed by a D. For example, if the
data base file name is ABCD, the DDS member and
object name will be ABCDD.
*NONE may be specified to avoid the re-create of the
display file. You may prefer to create the display
file using the normal CRTDSPF command.
If RPGTYPE(RPG) is specified, the display file name
will be used in the RPG F spec and only 8 characters
may be entered. This requires the data base file
name to be 7 characters or less if *DFT is used.
The member and display file must not exist unless
REPLACE(*YES) 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.
Restrictions
------------
** A keyed data file with a key length greater than 0 must be
used. A multi-format logical file may not be used.
** A maximum of 5 key fields may exist in the keyed file.
** Key fields may not exceed 50 characters in length.
** Key fields may not be date (L), time (T), or timestamp (Z)
fields.
** Key fields may not use an ALIAS keyword.
** For RPG III, the maximum field length is 256 characters. The
subfile program will not be created if a field exceeds 256
characters.
The reason for the restriction has to do with the fact that
fields greater than 256 characters are treated as data
structures. Since the field will exist in both the keyed and
arrival sequence file formats, the compiler sends an error
stating that a field name cannot be used as both a data
structure and as a sub field.
Other RPG III restrictions for data base fields include:
-- Field names longer than 6 characters are not supported.
-- Binary 8 length fields are not supported.
-- Floating point fields are not supported.
-- Variable length fields are not supported.
-- Null capable fields are not supported.
** For RPG IV (RPGLE), the maximum field length is 1170 which is
the maximum size that will fit on one detail screen (1 line of
50 and 14 lines of 80). If a field exceeds 1170 characters,
it will be dropped and the subfile program will be created
without the large field. Null capable fields are not
supported.
** The following data types are supported: Character (A), Decimal
(P,S,B) Date (L), Time (T), and Timestamp (Z). Variable
length fields (W) are supported in RPGLE.
** Only character and decimal fields are supported for the
special validity checking options. The first 40 fields will
be assigned indicators to allow for reverse image and
positioning of the cursor if an error occurs. If more than 40
fields specify some validity checking, the excess is still
checked, but the reverse image and cursor positioning is
dropped. The error text describes the field in error.
** A limit of 20 screens exists for either the Display of a
record or the Change/Add displays. Each screen has a maximum
of 15 fields. Fields with 50 characters or less take one
line. If a field exceeds 50 characters, each extra line will
hold 80 characters.
A single field will not be split over multiple screens. If
the screen layout would cause a split, a new screen is
started.
Thus a file containing 300 fields where each field is 50
characters or less may be completely displayed (20 screens x
15 lines). If more fields exist than can fit, they will be
dropped, but the subfile program will be created.
** The maximum number of fields which can exist in a file to be
used by CRTSFLPGM is 998.
** A field with a length greater than 50 characters will not be
generated for the subfile display.
** 'Position To' fields are provided at the top of the display
for the key fields of the file. It may not be possible to fit
all key fields on the line in which case the excess is dropped
and a message appears in the listing.
** The description of a 'Position to' field may be up to 15
characters.
** There is one line of column heading for each subfile field.
Two or 3 lines may be requested, but only the text
descriptions for the last line are provided for. A source
editor must be used to add any other lines once the display
file has been created. The minimum length for each column
width is 3 characters.
** The field description in the Display of a record or the
Change/Add display must be 23 characters or less. The 23
character limit also applies to the subfile column
descriptions.
** Single quote characters in any text description are
automatically doubled to allow the proper display. If
consecutive quotes exist such as "O''Neil", they are left as
is. The double quotes will appear when the samples are
displayed and are stored in the display file in the same
manner. When the display file is created, the system will
turn them into single quotes.
** The program that is created will invoke TAA functions during
run time which requires the TAATOOL library to exist on the
system the program is called on.
Prerequisites
-------------
The following TAA Tools must be on your system:
ABORT Abort
ADJVAR Adjust variable
CHKDAT3 Check date 3
CHKLIBL Check library list
CVTTIM Convert time
DSPDBFA Display data base file attributes
DSPFMT Display format
DSPMBRD Display member description
FILEFDBCK File feedback
HLRMVMSG HLL Remove message
LOCKMSG Lock message
RPGSTSDS RPG status data structure
RTVDAT Retrieve date
RTVDBFA Retrieve data base file attributes
RTVFLDA Retrieve field attributes
RTVFLDARR Retrieve field array
RTVKEYLST Retrieve key list
RTVLFMD Retrieve logical file member
RTVFMT Retrieve format
RTVSYSVAL3 Retrieve system value 3
RTVVALA Retrieve value attributes
SNDCOMPMSG Send completion message
SNDESCINF Send escape information
SNDESCMSG Send escape message
SNDSTSMSG Send status message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
CRTSFLPGM *CMD TAASTDH QATTCMD
RPLSFLPGM *CMD TAASTDH2 QATTCMD
TAASTDHC *PGM CLP TAASTDHC QATTCL
TAASTDHC2 *PGM CLP TAASTDHC2 QATTCL
TAASTDHC11 *PGM CLP TAASTDHC11 QATTCL
TAASTDHR11 *PGM RPG TAASTDHR11 QATTRPG
TAASTDHR12 *PGM RPG TAASTDHR12 QATTRPG
TAASTDHR13 *PGM RPG TAASTDHR12 QATTRPG
TAASTDHR21 *PGM RPG TAASTDHR21 QATTRPG
TAASTDHR22 *PGM RPG TAASTDHR22 QATTRPG
TAASTDHR23 *PGM RPG TAASTDHR23 QATTRPG
TAASTDHP *FILE PF
TAASTDHD *FILE DSPF TAASTDHD QATTDDS
TAASTDHE *FILE DSPF TAASTDHE QATTDDS
TAASTDHF *FILE DSPF TAASTDHF QATTDDS
TAASTDHG *FILE DSPF TAASTDHG QATTDDS
TAASTDHH *FILE DSPF TAASTDHH QATTDDS
The name TAASTDHA appears in the generated RPG source as the name of
the arrival sequence file. This file does not exist in TAATOOL and
is overridden at run time to the keyed file name.
The file TAASTDHP contains the source for the display file, RPG, and
RPGLE. Positions 1-5 uses a value that is read by TAASTDHR to
generate the source. Statements without a value in 1-5 are ignored.
Some statements are copied as is and some are modified.
Structure
---------
CRTSFLPGM Cmd
TAASTDHC CL
TAASTDHR11 RPG Rejects RPG for Binary 8, flt point, etc
TAASTDHR12 RPG Rejects RPGLE floating point
TAASTDHR RPG Main processing program
TAASTDHD DSPF Menu
TAASTDHR21 RPG Detail field description changes
TAASTDHE DSPF
TAASTDHR22 RPG Position to changes
TAASTDHF DSPF
TAASTDHR23 RPG Column heading changes
TAASTDHG DSPF
RPLSFLPGM Cmd
TAASTDHC2 CL
Run time of the created program
TAASTDHC11 Gets level ID and other parameters
TAASTDHR13 Displays validity checking information TAASTDHH
Display
|
