The Format Options tool provides an assist when several lines are
required to describe options or command keys in a typical subfile
application. For example, on the WRKMBRPDM display there are two
lines for option descriptions and two lines for command key
descriptions. However, there are more options and command keys than
fit in two lines. Generating the proper display lines is simplified
by the use of FMTOPT.
FMTOPT may also be used when the options or command keys must vary
depending on the user or some dynamic function within the program.
To better understand the FMTOPT tool, consider the following cases:
** WRKMBRPDM displays two lines of option descriptions, but 4
lines of information exist. There are 2 lines of command key
descriptions, but 8 lines exist. Two command keys are
assigned to roll thru the available information (F23=More
options and F24=More keys). Both F23 and F24 must appear for
any command key descriptions. Formatting these types of lines
can be very awkward and can be difficult to change when
enhancements are required.
** FMTOPT can also be used when an option or command key
description should not be displayed because of who the user is
or some dynamic function within the program. Assume that a
subfile normally displays the following option line:
2=xxxx 3=xxxx 4=xxxx
If the user is not authorized to use Option 3, the best user
interface is to not show it.
Rather than have the option line look like:
2=xxxx 4=xxxx
the FMTOPT tool can be used to make it appear as:
2=xxxx 4=xxxx
The FMTOPT tool is a program (TAADSPMC). Input data and options are
passed to the program with a single parameter (an externally
described data structure). On return, a field within the data
structure will contain the formatted lines for the display.
An array of descriptions is intended to be used to load the input.
An array of formatted lines can be used to extract the output. See
the example RPG code.
A demonstration command exists to allow you to see how the display
lines would appear.
DMOFMTOPT
An information display is first shown. When Enter is pressed, a
command prompt appears for a test command (TSTFMTOPT) that includes
test data (rollup to see the sample F key descriptions). You can
make changes (such as adding or subtracting the number of F key
descriptions, changing text, etc).
When Enter is pressed, the display of two formatted lines appear. If
more than two lines of information are available, F24 can be used to
roll thru the lines.
When Enter is pressed, you are returned to the TSTFMTOPT command
prompt to allow you to make changes and see how the lines are
dynamically reconstructed.
Be sure to try 'Fixed length descriptions = *YES' so you understand
this concept.
A sample RPG program exists that includes instructions for how to use
the FMTOPT function. See the section on 'Sample program'.
FMTOPT Data Structure
---------------------
The Externally Described File TAADSPMP may be used to define the Data
Structure that is used for communication to and from the FMTOPT
supplied program (TAADSPMC).
The length of the Data Structure is 6200 bytes.
You may display the format with the command:
DSPFMT TAADSPMP
Several of the fields have defaults. If the value is blank in the
Data Structure, the default is assumed.
FMSPCS The number of spaces between descriptions. The
default is 4. It must be a value between 1 and 9.
Position 1 of the Data Structure is used.
FMLINL The length of each line to be returned. The default
is 78 to allow the line to start in position 2 of a
display line. It must be a value between 50 and
200.
Positions 2-4 of the Data Structure are used.
FMFIXL Whether to format each line with the same length
description. The default is N to allow each line to
be formatted separately.
Y may be specified to format each line so that the
descriptions align. The length of the longest
description is used to determine the length of each
description display area. The FMLST1 and FMLST2
descriptions are also considered when determining
the longest description.
Aligning the descriptions can help make the display
easier to read, but is primarily of value when the
descriptions are approximately the same length.
Position 6 of the Data Structure is used.
FMDSPL The number of lines that are intended for the
display. The default is 2. The normal solution is
2 lines of options and 2 lines of command keys such
as shown on the WRKMBRPDM display. This does not
restrict how many lines will be returned in FMOUTL.
A value of 1-9 must be specified.
The value is only meaningful if FMLST1 or FMLST2 is
specified. This allows the program to determine
where the descriptions of FMLST1 and FMLST2 should
be placed.
Position 7 of the Data Structure is used.
FMLST1 The first of the last descriptions. The default is
blank meaning there is no description.
This field is intended for the case such as on
WRKMBRPDM where both F23 and F24 should appear on
each set of command key descriptions displayed. The
typical use would be to enter 'F23=More options' if
the options require more than 2 lines.
If a value is entered into FMLST1, a value must also
be entered into FMLST2.
Positions 7-56 of the Data Structure are used.
FMLST2 The second of the last descriptions. The default is
blank meaning there is no description.
This field is intended for any case where either the
option descriptions or the command key descriptions
take more than one line. The typical use would be
to enter 'F23=More options' or 'F24=More keys'.
If both the option descriptions and the command key
descriptions take more than 2 lines (such as on
WRKMBRPDM), then FMLST1 would normally be used for
'F23=More options' and FMLST2 for 'F24=More keys'.
Positions 57-106 of the Data Structure are used.
FMLINC A return value that describes the number of lines
that exist in the FMOUTL field. The field is
defined as *CHAR 2.
Positions 107-108 of the Data Structure are used.
FMRSV1 A reserved area.
Positions 109-200 of the Data Structure are
reserved.
FMI The input descriptions. This is a 3000 byte area
with 50 bytes for each description (up to 60
descriptions). The intended use is to allow you to
define an array of 50 byte elements and fill the
array with your descriptions.
Any blank values are ignored. For example, this
allows you to pass an array of 3 descriptions and
receive back a formatted line for normal use in the
program. However, during processing you may have a
condition where the middle option should not appear.
Just blank the second description and call the
FMTOPT program again. The blank value is ignored.
Positions 201-3200 of the Data Structure are used.
FMO The output lines. This is a 2964 byte area that may
be defined as less in your program. The normal
definition is to define an array of 38 elements with
a length of 78 (38 x 78 = 2964). The length of each
line as defined by the FMLINL value (default is 78)
determines the layout of the area.
The intended use is to define an array to match the
FMLINL value and then move the elements as needed.
Positions 3201-6164 of the Data Structure are used.
FMRSV2 A reserved area.
Positions 6165-6200 of the Data Structure are
reserved.
Sample program
--------------
A sample working program exists with instructions about how to use
the FMTOPT function. The code shown assumes only one set of
descriptions is handled by FMTOPT.
Most of the code is standard and can be copied as is if you use 2 78
byte lines for the display. You must use your own descriptions in
the array provided.
To run the program, do:
CALL TAATOOL/TAADSPMR11
You may copy the sample code from the archive with the command:
CPYTAA TAAARCMBR(TAADSPMR11) TOSRCF(xxx)
Then use a source editor to look at the source and read the
instructions for how to use of FMTOPT.
The sample display file is TAADSPMF which may also be copied from the
archive.
FMTOPT escape messages you can monitor for
------------------------------------------
None. Escape messages from based on functions will be re-sent.
DMOFMTOPT Command *CMD
------------------
No command parameters exist.
TSTFMTOPT Command *CMD
------------------
DESCRP The descriptions to be used for the options or
command key lines. Up to 30 bytes may be entered
for each of 60 descriptions.
Note that the length when using the FMTOPT program
is 50. A shorter length is used for TSTFMTOPT to
simplify presentation.
SPACES The number of spaces between descriptions. The
default is 4. The value must be between 1 and 9.
This value is passed to the FMSPCS field.
FIXLEN A *YES/*NO parameter for whether fixed length
descriptions should be used. The default is *NO so
each line is formatted independently of any other
line.
If *YES is specified, the longest description
(including the LSTDS1 and LSTDS2 parameters) is used
to determine the length of each description
displayed.
The value entered is translated to Y or N and passed
to the FMFIXL field.
LSTDS1 The 1st of the last descriptions. This value will
appear on each set of lines displayed. The
parameter is intended for the case where both the
option and command key descriptions exceed 2 lines
and both F23 and F24 (as shown on WRKMBRPDM) are
needed. The F23 text would be placed in the LSTDS1
field.
*NONE may be entered for no description.
The value is passed to the FMLST1 field. If LSTDS1
has a value, LSTDS2 cannot be *NONE.
LSTDS2 The 2nd of the last descriptions. This value will
appear on each set of lines. The parameter is
intended for the case where 1) both the option and
command key descriptions exceed 2 lines and both F23
and F24 (as shown on WRKMBRPDM) are needed or 2)
either the option or command key descriptions exceed
2 lines.
*NONE may be entered for no description.
The value is passed to the FMLST2 field.
Restrictions
------------
None.
Prerequisites
-------------
The following TAA Tools must be on your system:
DSPERRMSG Display error message
EDTVAR Edit variable
EXTLST Extract list
SNDCOMPMSG Send completion message
SNDESCMSG Send escape message
Implementation
--------------
None, the tool is ready to use.
Objects used by the tool
------------------------
Object Type Attribute Src member Src file
------ ---- --------- ---------- ----------
DMOFMTOPT *CMD TAADSPM2 QATTCMD
TSTFMTOPT *CMD TAADSPM3 QATTCMD
TAADSPMC *PGM CLP TAADSPMC QATTCL
TAADSPMC2 *PGM CLP TAADSPMC2 QATTCL
TAADSPMC3 *PGM CLP TAADSPMC3 QATTCL
TAADSPMR11 *PGM RPG TAADSPMR11 QATTRPG
TAADSPMD *FILE DSPF TAADSPMD QATTDDS
TAADSPME *FILE DSPF TAADSPME QATTDDS
TAADSPMF *FILE DSPF TAADSPMF QATTDDS
Structure
---------
TAADSPMC - Format Option program (CL)
DMOFMTOPT Cmd
TAADSPMC2 CL pgm - Uses TSTFMTOPT
TAADSPMD Display file
TSTFMTOPT Cmd
TAADSPMC3 CL pgm - uses TAADSPMC
TAADSPME Display file
TAADSPMR11 RPG Pgm - Sample
TAADSPMF Display file
|
