TAA Tools
FMTOPT          FORMAT OPTIONS                         TAADSPM

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
					

Added to TAA Productivity tools June 1, 2002


Home Page Up to Top