TAA Tools
CRTCMDHLP       CREATE COMMAND HELP TEXT               TAACMDL

The Create  Command Help  Text command  builds the base  UIM help  text
that is  needed for providing command  help text.  After  the base help
text  is built,  you would  use SEU to  insert the  specific words that
will be displayed as the help text.

CRTCMDHLP finds  the source  that was used  to create  the command  and
creates the UIM tags needed for:

  **   Command level help

  **   Help for each parameter

A typical command would be entered as:

           CRTCMDHLP   CMD(TST1) CMDHLPMBR(UIM1)

This  would access  the TST1  command definition  object.   The command
name  and object text  would be used  to create the  command level help
text.   Each  KWD  parameter that  was  used  in the  source  would  be
accessed and the  name of the parameter  and the value entered  for the
PROMPT  parameter (if any) would  be used to create  the parameter text
for each parameter.  The UIM tags  would be written to the UIM1  source
member of the QPNLSRC source file.

If the  CMDHLPMBR member  does not  exist, it  is added  to the  source
file.  If  there are no records in  the member, the ':PNLGRP' statement
is  added.  The  help text is  then added to  the member.   If the last
statement  found in  the  member  is  :EPNLGRP., the  first  output  is
written over  this tag.   An :EPNLGRP.   tag is  always written  at the
end of the source.

Getting started
---------------

You  would normally use  the same command  help member  to provide help
text for  multiple commands.   Thus  you would  begin a  new member  my
specifying:

  (The ':' begins in position 1 of the source)

   :PNLGRP.
   .*
   .*   Any text you wanted (eg the command names)
   .*     to help describe the text.
   .*

You would then use  CRTCMDHLP for each command that  you want to supply
help text for and name the same member such as:

           CRTCMDHLP   CMD(TST1) CMDHLPMBR(UIM1)
           CRTCMDHLP   CMD(TST2) CMDHLPMBR(UIM1)

If  there  are no  statements in  the  CMDHLPMBR, the  :EPNLGRP  tag is
output first.  If statements  already exist, all additional  statements
are added.

Modifying the base UIM output
-----------------------------

Assume you are  creating help text for  a command such as the  TAA Tool
RPLDSPF.   Assume that there is only a  single parameter (FILE) for the
display  file  name.   The  source  member  has a  text  description of
'Replace display file - RPLDSPF'

The command definition source would look like:

             CMD        PROMPT('Replace Display File - TAA')
             PARM       KWD(FILE) TYPE(QUAL1) MIN(1) +
                          PROMPT('Display file name')
 QUAL1:      QUAL       TYPE(*NAME) LEN(10)
             QUAL       TYPE(*NAME) LEN(10) DFT(*LIBL) SPCVAL(*LIBL) +
                          PROMPT('Library name')

After the CRTCMDHLP  command completes, the  base help text would  look
as follows:

  (The '.' begins in position 1 of the source)

  .****************************************************************
  .*                                                              *
  .*   RPLDSPF     Replace display file - RPLDSPF                 *
  .*                                                              *
  .****************************************************************
  :HELP name=RPLDSPF.
  Replace display file - RPLDSPF
  :P.
  cccccccccc This is where command level help goes.
  :EHELP.
  :HELP name='RPLDSPF/FILE'.
  Display file name (FILE) - Help
  :XH3.Display file name (FILE)
  :P.
  pppppppppp This is where the parameter level help goes.
  :EHELP.

The  line that  begins  'cccc' is  where  the command  level help  text
goes.   You can enter as  many lines as you want.   Each paragraph must
begin with a :P.  UIM tag.   Each :P.  causes a blank line  followed by
the  text  you  supply.    The text  is  automatically  placed  into  a
paragraph.   The text must  begin at position  1 of the  source and any
embedded blanks that you  enter will appear in  the object text.   Thus
it might look like:

  :P.
  The Replace Display file command allows you to name a
  display file object and the object will be recreated using
  the source member that was originally used. Any existing
  authorizations are retained.
  :P.
  All you need to do is change the DDS source and specify RPLDSPF.
  Any attributes from the existing display file are accessed
  and automatically specified for the new object.

The line  that begins  'pppp' is  where the parameter  level help  text
goes.   You  can enter as  many lines  as you  want and  each paragraph
must begin with a :P.  UIM tag.

For  each keyword  found for  the command,  the base structure  of help
text beginning with :HELP and ending with :EHELP would be created.

See  the  later  section for  additional  UIM  tags  you  may  want  to
consider.

Creating the panel group
------------------------

After you have  changed the member with SEU to  add specific help text,
you would use CRTPNLGRP to create the *PNLGRP object such as:

           CRTPNLGRP   PNLGRP(UIM1)

Modifying the command
---------------------

To modify the command you have provided help text for:

           CHGCMD   CMD(TST1) HLPPNLGRP(UIM1) HLPID(*CMD)

When  you prompt for the TST1 command,  help text would be available at
both the command level and the parameter level.

Special handling of prompt text
-------------------------------

When a return variable  exists on a prompt,  the system solution is  to
show the attributes in parenthesis such as:

             Return date             (6)

The excess  blanks before the  (6) read well  on the prompter,  but not
in  the command  help text.   Therefore, the  code squeezes  out excess
blanks of the prompt so that the value in the help text would read:

             Return date (6)

Command parameters                                    *CMD
------------------

   CMD           The qualified name of the  command to build help  text
                 for.   The library defaults  to *LIBL and  *CURLIB may
                 also be specified.

   CMDHLPMBR     The  member of  the command  help  file to  be written
                 to.   If  the member  does not  exist, it is  added to
                 the file.

   CMDHLPFILE    The qualified name of  the source file to be  used for
                 the  CMDHLPMBR.   The file  name defaults  to QPNLSRC.
                 The  library name  defaults to  *LIBL and  *CURLIB may
                 also be specified.

   ESCAPEMSGS    A *YES/*NO value for  whether the command help  should
                 include a  section for  Escape Messages.   *NO  is the
                 default which does not output the help section.

                 *YES  may be  specified to  output  a section  of help
                 text for  Escape  messages.   *YES  is  used  for  TAA
                 Commands.

   DFTHELP       Whether to insert  'cccc...' for the command  help and
                 '.pppp....'  for the  parameter help  or  phrases such
                 as 'No help text provided.'

                 *STD is the default to insert 'cccc...'.

                 *NOHELP  may be entered to  insert 'No help provided'.

   FLAG          Whether to  add a  flag to  the command  title in  the
                 help.    *NONE  is  the  default meaning  no  flag  is
                 added.

                 A  flag may  be used to  identify what  the command is
                 part of when the help text is displayed.

                 Up to 5 characters may  be entered to be added to  the
                 command title.   A blank will follow the  last byte of
                 text  followed  by a  dash followed  by  another blank
                 and then the  flag value.   For example, if  FLAG(DEF)
                 was specified  and the command  object text  is 'ABC',
                 the command help text prompt would be 'ABC - DEF'.

   LEADCOMMNT    A  *YES/*NO  parameter  for  whether  to  include  the
                 PNLGRP/EPNLGRP   lines   and   the   leading   box  of
                 comments.

                 *YES is the default to include these.

                 *NO may be specified to bypass this output.

Additional UIM functions to consider
------------------------------------

To provide  only basic  help text,  you need  only the  base help  text
provided  by  CRTCMDHLP  and  the  use  of additional  :P.    UIM  tags
whenever you want to start a new paragraph.

Another  function  you might  want  to consider  is the  use  of LINES.
This allows you  to specify a string  of text which  could be a  sample
command or a series of points such as:

  (The ':' begins in position 1 of the source)

  :LINES.
     - This is the first bullet
     - This is the second bullet
  :ELINES.

A  pair  of LINES/ELINES  must  appear  between  the :HELP  and  :EHELP
commands.

A blank  line automatically appears before the set  of lines.  The line
is not formatted  by UIM.   You can  follow or precede  the LINES  with
paragraphs.

UIM does  not  allow a  specific amount  of indentation.   Because  the
indentation  varies depending  on  whether you  are  displaying command
level  help  or  parameter  level  help,  UIM  dynamically  adjusts the
indentation.

If you  want to cause  indentation, you should  use the PARML  command.
The following would be indented:

  :PARML.
  :P.
  This is how you indent a paragraph
  so that some of the text will look better.
  :EPARML.

System Style Help Text
----------------------

The  help  text for  system  commands  is  more elaborate  than  simple
paragraphs  and lines.  Assume  you have a command  called TSTHELP with
the following command definition:

/* TSTHELP command which is used for a demo of help text            */
             CMD        PROMPT('Test Help -1')
             PARM       KWD(SRCFILE) TYPE(QUAL1) MIN(1) +
                          PROMPT('Source file name')
             PARM       KWD(OUTPUT) TYPE(*CHAR) LEN(6) DFT(*) +
                          RSTD(*YES) VALUES(* *PRINT) +
                          PROMPT('Output')
 QUAL1:      QUAL       TYPE(*NAME) LEN(10)
             QUAL       TYPE(*NAME) LEN(10) DFT(*LIBL) +
                          SPCVAL(*LIBL *CURLIB) +
                          PROMPT('Library name')

The following would  be the UIM  code to provide  help text that  would
emulate the  approach used by  the system.   The beginning of  a second
command  TSTHELP2 is  shown.   You  would normally  have a  panel group
object for more than a single command.

               UIM Source for TSTHELP Command
               ------------------------------
:PNLGRP.
:HELP name=TSTHELP.
Test Help -1 - Help
:P.
This command does not execute, but is intended to
show how to do help text.
:EHELP.
:HELP name='TSTHELP/SRCFILE'.
Source file (SRCFILE) - Help
:XH3.Source file (SRCFILE)
:P.
Specifies the name and library for the source
file.
:PARML.
:P.The possible library values are:
:PARML.

:PT.:PK def.*LIBL:EPK.
:PD.The library list is used to locate the object.
:PT.:PV.*CURLIB:EPV.
:PD.The current library is used to locate the object.
:PT.:PV.library name:EPV.
:PD.Specify the library name where the object is located.
:EPARML.
:EPARML.
:EHELP.
:HELP name='TSTHELP/OUTPUT'.
Output (OUTPUT) - Help
:XH3.Output (OUTPUT)
:P.Specifies whether the output from the
command is displayed at the requesting workstation
or output to a printer.
:PARML.
:PT.:PK def.*:EPK.
:PD.The output is displayed (if requested by an
interactive job) or printed if requested by
a batch job.
:PT.:PV.*PRINT:EPV.
:PD.The output is printed with the job's spooled
output.
:EPARML.
:EHELP.
:HELP name=TSTHELP2
Test Help -2 - Help
:P.
This is the beginning of the help text for another command.
You normally want a single member of help text for
multiple commands. Not all of the help for the command is shown.
:EHELP.
:EPNLGRP.

          Explanation of UIM Source for TSTHELP Command
          ---------------------------------------------

  **   The :PNLGRP.  and :EPNLGRP.  tags  begin and end the text.   You
       normally want the  help text for  multiple commands in  a single
       member so that they will appear in a single PNLGRP object.

  **   You may  enter any comments with an entry  of '.* xxx' beginning
       in position 1.  None are shown in the example.

  **   The  HELP name=XXXX.   tag  identifies the  name of  the command
       TSTHELP which the help text is being supplied for.

  **   The :P.   tag says the  text that follows is  a paragraph.   The
       text  for  the  paragraph  can  be  on  the  same  line.    This
       paragraph  identifies  the command  level  text.   You  can have
       multiple paragraphs.

  **   The :EHELP tag ends the command level help text.

  **   The HELP  name  ='xxx/yyy' tag  identifies  the  command/keyword
       that the  help text  is being  supplied for.   The line  of text
       after  the keyword is  the text that  will appear at  the top of
       the help for the keyword.

  **   The :XH3  tag  is  a  heading line  that  will  only  appear  if
       command level  help is requested.   This causes  highlighting of
       the text.

  **   The  next paragraph  identifies the  high  level info  about the
       keyword (parameter).

  **   The  :PARML.  tag begins a  parm list group.   It is ended by an
       :EPARML.   tag.    In  this  case  there are  two  PARML  groups
       because the  library is  a qualified name  and the  second piece
       is being described.

  **   The  first PARML tag just says 'The  possible values are'.  This
       causes indentation.   The 2nd  PARML tag  causes indentation  of
       the values that can be entered.

  **   The  :PT.   tag  causes  highlighting.   The  :PK.   def.    tag
       identifies  a keyword  value  that is  the default.    The value
       will be underscored.   The  value *LIBL  is then  entered.   The
       :EKP.   tag  ends  the value.    The :PD.    tag identifies  the
       description of the value.

  **   The PT:PV.*CURLIB:EPV.   tags say  that this is  another keyword
       value,  but  it is  not  the default.    The value  *CURLIB will
       appear.  The :PD.  tag describes the text for the value.

  **   Another  :PT.:PV.xxxx:EPV.    set  of  tags  identifies  another
       value for the keyword plus the :PD.  tag.

  **   The :EPARML.  tags end the preceding groups.

  **   The :EHELP.  tag ends the help for the SRCFILE parameter.

  **   Another   keyword  (parameter)   is  identified   by  the   HELP
       name='xxx' tag.   The first line of text  is used for the top of
       the display when help is  requested specifically for the  OUTPUT
       parameter.

  **   The :XH3.   tag describes the  highlighted heading that  is used
       when the command level help is described.

  **   A single level :PARML.  tag is used (no qualified name).

  **   The  :PT.:PK def.*:EPK.   set  of tags identifies  the *  as the
       default value.  The PD tag provides the text for the value.

  **   The :PT.:PV.*PRINT:EPV.   set of tags  provides another  keyword
       value *PRINT.  The PD tag describes it.

  **   The :EPARML.  tag ends the parameter list.

  **   The :HELP.  tag ends the help for the keyword.

  **   The :HELP name=TSTHELP2 tag begins the next command.

  **   The :EPNLGRP.  tag ends the source.

Restrictions
------------

You must  use the  keyword form  of the command  definition source  for
the KWD and PROMPT keywords.

The  command definition source  used to  create the command  must still
exist which was used to create the command.

Prerequisites
-------------

The following TAA Tools must be on your system:

     EDTVAR       Edit variable
     HLRMVMSG     HLL Remove message
     RTVDAT       Retrieve date
     RTVCMDA      Retrieve command attributes
     SNDCOMPMSG   Send completion message
     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
   ------        ----    ---------      ----------    ----------

   CRTCMDHLP     *CMD                   TAACMDL       QATTCMD
   TAACMDLC      *PGM       CLP         TAACMDLC      QATTCL
   TAACMDLR      *PGM       RPG         TAACMDLR      QATTRPG
					

Added to TAA Productivity tools May 1, 1996


Home Page Up to Top