TAA Tools

In some environments,  it is desirable  to provide a menu  or selection
function  similar to system  displays and allow  for a command  line at
the bottom of the display.

A  similar approach could also  be used if you  want to create your own
command entry display to  either control what commands get  executed or
to provide  a more  permanent audit  trail of what  was executed.   For
example,  if  you  want  to audit  what  commands  are  entered  by the
security officer,  you could  provide your  own  command entry  display
and write the commands to a journal using SNDJRNE.

The  system supports  an API  for a  command line.   The  API places  a
window  on  top of  the  current display  and  allows a  command  to be
entered.  This  is much  simpler to implement,  but does  not give  the
same  appearance as  a  system  menu.   Normally,  you would  define  a
function key on  a display to request the  command line.  When pressed,
your code would do:

          CALL    QUSCMDLN

A  window would be  displayed with the command  line inside the window.

System displays  use UIM to  provide for  a command  entry line on  the
same  display  as  other  functions.    A command  entry  line  can  be
achieved  using  a  combination of  system  functions  to  simulate the
system displays.   The code  provided is  to be used  as skeleton  code
for  your  application  functions.     It  provides  for  both  options
(typical menu entries) and a command line:

Command line

  **   Commands may be entered and executed

  **   Messages are displayed using a message subfile

  **   The F9 key exists for retrieving previously executed commands

  **   The  F1/HELP keys exist  for accessing  the second level  of the

  **   Command prompting  is provided  by F4  or  by placing  a ?    in
       front of the command

  **   The commands  are  logged to  the job  log and  can be  executed
       again  as commands  (for example  if  the command  entry display
       was accessed)

  **   If  a  command  is  prompted  for  and  exceeds  the  two  lines
       available,  it will  still  be  properly  executed  and  can  be
       retrieved with F9.

  **   If the  user is LMTCPB(*YES),  the command line will  reject the
       request unless the command specified is ALWLMTUSR(*YES).


  **   If  an option  is successful  (no escape message),  the messages
       received by  the  program  (sent  by your  application)  do  not
       appear on the display.

  **   A sample is shown  for how to place a  completion message on the

  **   Two forms of error handling are shown:

         --   If  an option  is  unsuccessful (escape  message occurs),
              the  program  does  DSPJOBLOG  and  sends  a  message  to
              QSYSOPR  informing  the  operator  that   an  option  has
              failed.    Options  are  normally well  tested  functions
              that  if they  fail you  want to  ensure that  the proper
              debugging information exists.   You could send  a message
              to  a  different  queue.    The operator  sees  a  status
              message  while  the  job  log  is  being  printed  and  a
              general failure message when completed.

         --   If an  option is  unsuccessful (escape  message  occurs),
              the  messages associated  with the  error  are placed  in
              the message subfile.

Message logging differences

There  is  a  difference  in  how  messages  are  sent to  the  message
subfile.  When  a system menu  has a command  line, any escape  message
is sent as a  diagnostic message.  Since other  diagnostic messages may
also  occur, this  can  make it  difficult  to determine  which  is the
actual  escape  message.    The CMDLINE  function  displays  the escape
messages as escape messages.


  **   If  a  command  is  prompted  for,  the  command  string  to  be
       executed cannot exceed 512 bytes.

  **   If F9  is used, only  commands executed from this  invocation of
       the program can be retrieved.

    - If F9 is used, the previous 100 commands can be retrieved.


The  demonstration  program  exists  so you  can  try  the  function by

         CALL   TAACMDBC

The intent of the code is  that you would copy it for your  application


The following TAA Tools must be on your system:

          SNDESCMSG    Send escape message
          SNDSTSMSG    Send status message


The demonstration program is ready to use.

To implement your own requirement do the following:

  **   Use CPYTAA  to copy  the following  members to  your own  source
       file(s) and use your own source member names.

            Member       Type
            ------       ----

            TAACMDBC     CLP
            TAACMDBD     DSPF
            TAACMDBR     RPG

  **   Modify  the DDS source.   Statements within  the source describe
       what should be modified.

         --   At about  statements 9.00  - 10.00  is the  text for  the
              title of the display.

         --   At about  statements 17.00 -  30.00 are the  options that
              are valid  and their text  descriptions.  These  begin on
              the  display on line 6 and can  go thru line 17 (room for
              12 options).   Change the  options and  the text to  meet
              your needs.   A two digit  option is valid.   The options
              must be digits 0 -9.

              Create the display file.

  **   Modify  the RPG source.   Statements within  the source describe
       what should be modified.

         --   At about  statement  3.00  is  the name  of  the  display
              file.  Use the one you created instead of TAACMDBD.

         --   At about  statement 13.00 is the  name of the  CL program
              that  will  be   used.    Insert  your  name  instead  of

              Create the RPG program.

  **   Modify the CLP  source.  Statements  within the source  describe
       what should be modified.

         --   At  about statement  4.00  is  the  name of  the  display
              file.    Use  the   name  that  you  created  instead  of

         --   At  about  statement 23.00  is  the name  of  the display
              file in  an  OVRDSPF  command.   Use  the name  that  you

         --   At  about  statements  96.00   -  124.00  are  where  the
              options  are  handled.    Modify  the  samples  as shown.
              Leave the GOTO  and MONMSG commands in  place.  Add  more
              options  to match  what  you  specified for  the  display

              Do  not include any completion  messages for your options
              to appear  on the  display  at this  point in  the  code.
              See the later discussion of completion messages.

         --   At about  statement 215.00  is where  the RPG program  is
              called the  first time.   Change the name  to the program
              name you created instead of TAACMDBR.

         --   At  about  statement  258.00  is  where  the  job  log is
              printed if  an error  occurs on  an option.   The  output
              will be  directed to the OUTQ described  for the QPJOBLOG
              file.   You can direct  this output to a  special file by
              doing  an  override  at  this  point.    Note  that  this
              technique is effective  during a job, but  cannot be used
              to  direct the  job log at  the end  of the  job.The code
              you would add is:

                     OVRPRTF     FILE(QPJOBLOG) OUTQ(xxxxx) +
                     DSPJOBLOG   OUTPUT(*PRINT)
                     DLTOVR      FILE(QPJOBLOG)

         --   At about statement 268.00 is  where a message is sent  to
              QSYSOPR to  describe that one  of the options  has failed
              and a  job log has been printed.   You can change this to
              a   different   message  queue,   send   it  also   to  a
              programmer's message queue, change the text, etc.

         --   At about  statements 296.00  -  301.00 is  where you  can
              insert  any completion  messages  for  options that  were
              taken.   This  is often desirable  if an  option does not
              perform an  interactive  display.   For  example,  if  an
              option submits  a batch  job, it  is generally  desirable
              to   provide   some   feedback   that   the  option   was
              successful.  At a minimum, delete the sample.

         --   At about statement  310.00 is  where the  RPG program  is
              called the  last time.   Change the  name to the  program
              name you created instead of TAACMDBR.

              Create the CL program.

You should be ready to try the function.

Objects used by the tool

   Object        Type       Attribute      Src member     Src file
   ------        -----      ---------      ----------     -----------

   TAACMDBD      *FILE         DSPF        TAACMDBD       QATTDDS
   TAACMDBC      *PGM          CLP         TAACMDBC       QATTCL
   TAACMDBR      *PGM          RPG         TAACMDBR       QATTRPG

Added to TAA Productivity tools April 1, 1995

Home Page Up to Top