14.5 @@GET_FILS Command
The @@GET_FILS command is used to ask for file(s) to be selected for use in the application template.
If more than 1 file can be selected, then after choosing the primary file, the user will be presented with a second list of all those files related in some manner to this selected primary file. This list will be in the form of a "tree" of relationships. For this "tree" of relationships to be built, all files involved will have to have been set up with access routes showing how all the files are related. If you have used data modeling to design your database then this will already have been done for you, otherwise you will have to manually add all access routes.
Some of the rules in selecting from this list are:
- When SGL_ONLY(*NO) has been specified, only one 1 : N (many) relationship may be chosen from the list displayed. Multiple 1 : 1 relationships may be selected.
- All higher levels in a relationship chain must be chosen before a lower level relationship can be selected.
- A maximum of (TO - FROM + 1) files may be selected.
This command creates/updates special variables @@TFMX and @@TFMN to contain the maximum and minimum file numbers chosen.
Optional
@@GET_FILS ----- FROM -------- 1 ----------------------------->
(number 1 - 50)
>---- TO ---------- 50 ---------------------------->
(number 1 - 50)
>---- PHY_ONLY---- *YES --------------------------->
*NO
>---- SGL_ONLY---- *YES --------------------------->
*NO
>---- PROMPT ----- 'text' ------------------------->
>---- EXTEND ----- 'text' ------------------------->
-- 8 max --
>-----HELPIDS ---- HELP panel identifiers ---------|
| |
-------- 10 max -----------
Parameters
FROM
Specifies the first file number to allocate to a user selected file. The default value is 1 and the maximum value is 50.
TO
Specifies the last file number to allocate to a user selected file. The default value is 50 and the maximum value is 50. The difference between the FROM and TO parameter values determines the number of files a user is able to select for this command. For example, if FROM(1) and TO(1) is specified then only 1 file may be selected. If FROM(1) and TO(50) is specified then 50 files may be selected by the user.
PHY_ONLY
Specifies whether only physical files will be presented for selection, or both physical and logical files.
SGL_ONLY
Specifies whether only 1 : 1 (single) relationships will be presented for selection, or both 1 : 1 and 1 : N (many) relationships.
PROMPT
Specifies the prompt text for the command. This is up to a maximum of 74 characters. The prompt text may contain special variables (refer to the 14.22.5 Special Template Variable Notes on special variables). More detailed prompt text can be placed in the EXTEND parameter.
EXTEND
Specifies the extended prompt text for the command if the PROMPT parameter cannot contain a full enough description required prompt. This is up to a maximum of 8 lines of 74 characters. The extended prompt may contain special variables.
HELPIDS
Specifies up to 10 HELP panel identifiers for this application template. These will be displayed as full page screens of HELP when the user presses the HELP function key.
Examples
The following examples apply to the @@GET_FILS command.
Example 1: Ask the user to select a single primary physical file.
@@GET_FILS FROM(1) TO(1) PHY_ONLY(*YES) PROMPT('Select +
the primary physical file to be worked with') +
EXTEND('Enter the name of the PHYSICAL file ....') +
HELPIDS(HELP010)
Example 2: Ask the user to select up to 20 related files. Both physical and logical files may be selected.
@@GET_FILS TO(20) PHY_ONLY(*NO) SGL_ONLY(*YES) PROMPT('Enter +
the name of the primary file to be used by this +
template') +
EXTEND('The file name may be specified in full, +
partially .....') +
HELPIDS(HELP020 HELP030 HELP040 HELP050)