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
|
