Provide help text for user commands.

This article is the seventh in a series related to creating user commands. The first five articles introduced how to define various command parameter features and then implement those features within the command's CL-based command processing program (CPP). Starting with the sixth article, "Providing Help Text for a User Command," we began looking at how to use the Generate Command Documentation (GENCMDDOC) command to provide a starting point for our help text. In this article, we will look at how to code User Interface Manager (UIM) text, which can be used to create and maintain our command help text.

Before changing the UIM text generated by the GENCMDDOC command, let's first see what we have to start with. Having generated the UIM source into member TRMLFTCHR of source file QPNLSRC in the previous article, use the following two commands to first create a panel group named TRMLFTCHR and then associate this panel group as the help panel group for the TRMLFTCHR command.

CRTPNLGRP PNLGRP(TRMLFTCHR)

CHGCMD CMD(TRMLFTCHR) HLPPNLGRP(*LIBL/TRMLFTCHR) HLPID(*CMD)

If you now prompt the TRMLFTCHR command and use F1 while the cursor is positioned on the prompt line containing the VAR parameter prompt, you will see the help text title "Value (VAR) – Help" followed by the help text:

Specifies <...>

This is a required parameter.

character-value

    Specify the <...>

If you use F1 while the cursor is positioned on the line above the VAR parameter prompt, you will see the default help text associated with the command, each parameter of the command, and examples for using the command. With this help text as our initial starting point, we will now enhance this default help with a description of what the TRMLFTCHR command really does when run.

Looking at member TRMLFTCHR of source file QPNLSRC with an editor such as SEU, you should find the first few lines of TRMLFTCHR being similar to the following:

:pnlgrp submsgf='VINING/USERMSGF'.                                    

.*********************************************************************

.*  Help for command TRMLFTCHR                                        

.*********************************************************************

:help name='TRMLFTCHR'.                                               

&msg(TRM0001). - Help                                                  

:p.The &msg(TRM0001). (TRMLFTCHR) command <...>                       

.* Describe the function provided by the command.                     

:p.:hp2.Restrictions::ehp2.                                           

:ul.                                                                   

:li.                                                                  

You must have <...>                                                   

.* List all special authorities required to run the command.          

:li.                                                                  

You must have <...>                                                   

.* List object or data authorities required to run the command.       

:li.                                                                   

This command is conditionally threadsafe, <...>                       

.* If conditionally threadsafe, list threadsafe conditions or restrictictions.

:li.                                                                   

<...>                                                                 

.* Describe other command-level restrictions.                         

.* Parameter-level restrictions belong in parameter help sections, not here.

:eul.                                                                  

:ehelp.

What you are seeing is UIM source defining the initial help text for the command TRMLFTCHR. UIM is a tag-based language, meaning that certain tags, or commands, are imbedded in the source to define various elements of the document. In our case, the document is the help text for the TRMLFTCHR command. The tags are surrounded by common start and stop characters. For UIM, the tag start character is a colon (:) and the end character is a period (.). Another tag-based language that you might be familiar with is HTML. In the case of HTML, the tag start character is the less-than symbol (<) and the end character is the greater-than symbol (>). Associated with each UIM tag can be zero, one, or more attributes.

The first source line, :pnlgrp submsgf='VINING/USERMSGF'., is a panel group (pnlgrp) tag with one attribute specified, submsgf='VINING/USERMSGF'. The pnlgrp tag defines the start of a panel group definition, and only one pnlgrp tag can be used in the source member. The associated epnlgrp tag defines the end of the panel group definition. The submsgf attribute allows you to specify the default message file to be used when the &msg symbol is encountered in the panel group definition. You might recall from the previous article that the &msg symbol can be used to substitute the first-level text of a message description, within the help text document, when the &msg symbol identifies a message ID. The value found in the generated source, VINING/USRMSGF, is based on the value specified for the Prompt file (PMTFILE) parameter when creating the TRMLFTCHR command with the CRTCMD command.

The next three lines, those starting with a period and an asterisk (.*), are comments generated by the GENCMDDOC command. The comment must start in columns 1 and 2 of the source record.

Having defined the start of the panel group and provided a comment concerning what the panel group represents (help for command TRMLFTCHR), we're now ready to provide the actual help text. The next tag, :help, does just that. The help tag identifies the start of a help module and, similar to the pnlgrp tag, requires an associated ehelp tag to indicate the end of the help module. For command help, there are usually several help modules within the panel group. There is generally one help module introducing the function of the command, one help module for each parameter of the command, a help module for examples of how to use the command, and a help module documenting the possible escape messages the command can send. The TRMLFTCHR help panel group will follow this convention.

The first help tag has the attribute "name=TRMLFTCHR" and represents the help module introducing the command. is used because we specified HLPID(*CMD) when we earlier used the CHGCMD command to associate the TRMLFTCHR panel group as the help panel group (HLPPNLGRP) for the command. HLPID(*CMD) tells the i command prompter that help modules are identified by the name of the command.

Following the help tag is a &msg symbol identifying message ID TRM0001 and then the text " – Help." This indicates that the first line of the help module should show the first-level message text for message TRM0001 (which is to be found in message file VINING/USERMSGF due to the previous pnlgrp submsgf specification) followed by a space, a dash, a space, and then the text 'HELP'. As a reminder, the first-level message text for TRM0001 is "Trim Left Characters," so the line displayed will be "Trim Left Characters – Help."

Following this is a :p tag. The p tag indicates that a new paragraph of text is to start. The paragraph text, as provided by the GENCMDDOC command, is simply "The &msg(TRM0001). (TRMLFTCHR) command <...>". One possible enhancement for this paragraph would be along the lines of the following:

:p.The &msg(TRM0001). (TRMLFTCHR) command changes the value of a CL   

character variable by trimming (removing) specified characters from the left of the specified CL variable. The result is returned left adjusted and blank padded.                                                             

I'll point out that the &msg symbol has now been used twice to reference the first-level text of message TRM0001. Frequently used text, such as the name of the command, should be stored in a message description. Storing common text in a message, and referring to this text with the &msg symbol, greatly simplifies the task of changing the help text if a wording change is ever needed.

A new paragraph is then started with another p tag. This paragraph though, rather than starting with text, starts with another tag. The tag is hp2 and indicates that the following phrase is to be highlighted. There are 10 variations of highlighting with the 2 indicating white on a color display, high intensity on a monochrome display, and bold on a printer. Following the tag is the phrase "Restrictions:" and then the tag ehp2. The ehp2 tag, as you can most likely guess, identifies the end of the highlighted phrase.

Following this is another new tag, ul. The ul tag identifies the start of an unordered list, where unordered means that each entry of the list is identified by a common character such as a bullet (lowercase o), a hyphen (-), or dashes (--). This is in contrast to an ordered list (tag ol), where each entry of the list is identified by sequential numbers or letters. Each individual entry of the list is identified with the li (list item) tag with the end of the list indicated by either the eul or eol tag, depending on the type of list (unordered or ordered). As you can see in the GENCMDDOC-generated source, comments are provided suggesting the types of restrictions you may want to list. For now, we'll just go with one list item in the list of restrictions, as shown below.

:p.:hp2.Restrictions::ehp2.                                           

:ul.                                                                  

:li.                                                                  

The TRMLFTCHR command is valid only in CL programs.                    

:eul.                                                                 

Though not shown, you can nest lists (unordered and ordered). As our list represents a first-level list, each list item will be preceded by a bullet.

At this point, we're done with our introduction to the TRMLFTHCR command, so we will end the help module with the ehlp tag. Here's the entire help module:

:help name='TRMLFTCHR'.                                               

&msg(TRM0001). - Help                                                  

:p.The &msg(TRM0001). (TRMLFTCHR) command changes the value of a CL   

character variable by trimming (removing) specified characters from the left of the specified CL variable. The result is returned left        

adjusted and blank padded.                                                             

:p.:hp2.Restrictions::ehp2.                                           

:ul.                                                                  

:li.                                                                   

The TRMLFTCHR command is valid only in CL programs.                   

:eul.                                                                 

:ehelp.                                                               

A few observations to point out about the TRMLFTCHR help module shown above. You might have noticed that the text for the paragraph starts on the same source line as the p tag while the text for the list item starts on the following source line. This is a matter of personal preference. The text associated with the paragraph could just as well have started on the source line following the tag, and the text for the list item on the same source line as the tag. Blank spaces between the tag and the text are removed when creating, or compiling, the panel group. Along the same lines, each line of text within a paragraph will have trailing blanks trimmed to one blank, allowing, for instance, each source line of our introductory paragraph to end on an arbitrary word boundary. These observations on the text formatting performed by UIM are just a few examples of how UIM help can simplify your creation of textual material. You provide the text; UIM provides the consistent display of the text. Those of you who have created textual material in the past using DDS might appreciate this difference, along with the absence of explicit source continuation characters from line to line!

The next set of help modules are related to the individual keyword parameters defined by the TRMLFTCHR command. We will look at these modules, and the new tags and features they introduce, next month. In the meantime, if you just can't wait to dig into the next help module, you can find much of the UIM reference material in Appendix A: UIM Panel Group Definition Language of the Application Display Programming manual, which is located here.

If you would like to see what you've done so far, recreate the TRMLFTCHR panel group with this command:

CRTPNLGRP PNLGRP(TRMLFTCHR)

Then prompt the command, press F1 to access the help text associated with the VAR parameter (which we haven't changed yet), and then press F2 for extended help.

More CL Questions?

Wondering how to accomplish a function in CL? Send your CL-related questions to me at This email address is being protected from spambots. You need JavaScript enabled to view it.. I'll try to answer your burning questions in future columns.