Additional UIM capabilities provide more help text with user commands.

In the last article, "Need Some Help with That Command?", several User Interface Manager (UIM) tags related to the formatting of help text were introduced, including these:

• :pnlgrp and :epnlgrp to define a panel group along with the setting of default values for some of the tags that might be found in the panel group
• :help and :ehelp to define one or more help modules within a panel group
• :p to indicate the start of a paragraph
• :hp2 and :ehp2 to indicate the start and end of a highlighted phrase
• :ul and :eul to start and end a list of items
• :li to indicate the start of a list item

These tags were discussed as they related to the general help provided for the TRMLFTCHR command. This article will continue this discussion of UIM tags as we look at documenting how the various parameters of the TRMLFTCHR command work.

The GENCMDDOC command generated the following UIM source as a starting point for documenting the VAR parameter of the TRMLFTCHR command.

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

.*   Help for parameter VAR                                           

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

:help name='TRMLFTCHR/VAR'.                                           

&msg(TRM0002). (VAR) - Help                                           

:xh3.&msg(TRM0002). (VAR)                                             

:p.Specifies <...>                                                    

.* Describe the function provided by the parameter.                   

:p.This is a required parameter.                                     

:parml.                                                              

:pt.:pv.character-value:epv.                                         

:pd.                                                                  

Specify the <...>                                                    

.* Describe the function provided by the user-defined parameter value.

:eparml.                                                              

:ehelp.                                                              

The first three source lines, as you learned in the previous article, are comments as they start with the characters '.*' in positions one and two of the source. Following these comments is the help tag for the next help module within the panel group.

Unlike the help tag we looked at last month, which had a simple name of TRMLFTCHR and served as extended help for the command, this help module name utilizes an imbedded slash (/) character. The slash, when found within a name, serves as a delimiter. In this case, the name TRMLFTCHR/VAR indicates that the help module is for the keyword parameter VAR of the TRMLFTCHR command. If you prompt the TRMLFTCHR command and request help while the cursor is located on the prompt line containing the VAR parameter, this is the help module that is to be immediately displayed.  Because the name contains a slash, the name must also be enclosed within apostrophes.

Following the help tag is a msg symbol similar to that used in the previous help module. The msg symbol will extract the first-level text of message ID TRM0002 from message file VINING/USERMSGF, concatenate the first level text with the text ' (VAR) – Help', and display the result.

The next tag, xh3 for extended help heading type 3, is new. Extended help headings provide the heading used over contextual help. Extended help headings are formatted with one blank line before the heading and one blank line following the heading, and the heading itself can be formatted in one of four ways. For type 3 extended help headings, the text is left justified and shown in white on a color display or high intensity on a monochrome display. There are three other types of formatting:

• xh1—Text is centered, underlined, and shown in white on a color display or high intensity on a monochrome display.
• xh2—Text is left justified, underlined, and shown in white on a color display or high intensity on a monochrome display.
• xh4—Text is left justified, underlined, and shown in green on a color display.

After the xh3 heading are two paragraphs. The first paragraph is where you can describe the function of the parameter. One possible description is "Specifies the CL character variable whose value is to be changed." The second paragraph specifies that the parameter is required and is provided by GENCMDDOC due to the command definition indicating that a minimum of one value is required.

Following these paragraphs is a :parml tag. The parameter list tag defines the start of a list of possible parameter values and descriptions. Two required tags are used within the parameter list to define each possible parameter value. These tags are :pt to indicate the supported parameter term and :pd to describe the parameter term. Additional tags can be used in the term and description in order to control formatting. The parameter list, when all possible parameter values have been documented, is then ended with the :eparml tag.

In the case of the VAR parameter, there is only one supported parameter value: a CL variable defined as TYPE(*CHAR). So the first and only list entry for the VAR parameter uses a pt tag with the text 'character-value' to define the type of value expected. This text string is preceded by the programming variable tag :pv and followed by the end programming variable tag :epv. The pv tag will cause the text 'character-value' to be displayed as green on a color display and underlined. Following this is a pd tag where you can document the type of character value expected—in our case, a CL variable.

The complete help module for the VAR parameter, along with the help modules for the other two parameters— TRMCHR and ALLTRMCHR—might be defined as shown below.

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

.*   Help for parameter VAR                                         

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

:help name='TRMLFTCHR/VAR'.                                         

&msg(TRM0002). (VAR) - Help                                          

:xh3.&msg(TRM0002). (VAR)                                           

:p.Specifies the CL character variable whose value is to be changed.

:p.This is a required parameter.                                    

:parml.                                                              

:pt.:pv.character-value:epv.                                        

:pd.                                                                

Specify the name of the character variable.                          

:eparml.                                                            

:ehelp.

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

.*   Help for parameter TRMCHR                                      

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

:help name='TRMLFTCHR/TRMCHR'.                                        

&msg(TRM0003). (TRMCHR) - Help                                        

:xh3.&msg(TRM0003). (TRMCHR)                                          

:p.Specifies one or more character values to be trimmed from the left 

of the CL variable identified by the VAR parameter. Trimming of        

characters will end when a character value of the VAR parameter does  

not match any of the specified TRMCHR values.                         

:p.You can specify 50 values for this parameter.                      

:parml.                                                               

:pt.:pk def.0:epk.                                                    

:pd.                                                                   

Remove zero (0) values starting from the left of the VAR parameter    

value.                                                                

:pt.:pv.character-value:epv.                                           

:pd.                                                                  

Specify the characters to be trimmed from the left of the VAR         

parameter.

:eparml.                                                             

:ehelp.                                                              

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

.*   Help for parameter ALLTRMCHR                                    

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

:help name='TRMLFTCHR/ALLTRMCHR'.                                    

&msg(TRM0004). (ALLTRMCHR) - Help                                    

:xh3.&msg(TRM0004). (ALLTRMCHR)                                      

:p.Specifies the left adjusted value to be returned in the VAR       

parameter when only characters specified by the TRMCHR parameter are 

found in the VAR parameter. This character value will be returned in 

the leftmost position of the VAR parameter with all following         

character positions set to blanks.                                   

:parml.                                                              

:pt.:pk def.*TRMCHR:epk.                                             

:pd.                                                                  

The first specified TRMCHR parameter value is to be used when all    

characters of the VAR parameter are trimmed.                         

:pt.:pv.character-value:epv.                                         

:pd.                                                                  

Specify the character value to be returned when all characters of the

VAR parameter are trimmed.                                           

:eparml.                                                              

:ehelp.                                                              

You should recognize many of the UIM tags shown above, but there is one set of tags found in the TRMCHR and ALLTRMCHR help modules that you haven't seen before. Both the TRMCHR and the ALLTRMCHR parameters define a default value—0 for TRMCHR and the special value *TRMCHR for ALLTRMCHR. For these default values, you will notice that the pv and epv tags, while used with the VAR parameter list entry and the second list entry defined for the TRMCHR and ALLTRMCHR parameters, have been replaced with the programming keyword :pk tag and associated :epk. The pk tag identifies the following text as representing a programming key value that can be used with the command. When used with the DFT attribute, as it is the 0 value for TRMCHR and the *TRMCHR special value for ALLTRMCHR, the programming keyword is also being identified as the default value for the parameter. When the optional DFT attribute is specified, the programming keyword will be displayed underlined and white on a color display or high intensity on a monochrome display. When the DFT attribute is not specified, the programming keyword will be displayed white on a color display or high intensity on a monochrome display, without being underlined.

After all of the command parameters have been documented, CL command help generally provides one or more examples of how to use the command. The command usage examples are typically defined as a separate help module, with the following representing two examples.

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

.*                                                                   

.* Examples for TRMLFTCHR                                            

.*                                                                   

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

:help name='TRMLFTCHR/COMMAND/EXAMPLES'.                              

Examples for TRMLFTCHR - Help                                        

:xh3.Examples for TRMLFTCHR                                          

:p.:hp2.Example 1: Simple Command Example:ehp2.                      

:xmp.                                                                 

TRMLFTCHR  VAR(&CHAR10)                                              

:exmp.                                                               

:p.This command will trim all leading zero (0) values from the       

CL variable &CHAR10 and return the remaining characters left         

adjusted.                                                            

.*                                                                   

:p.:hp2.Example 2: More Complex Command Example:ehp2.                

:xmp.                                                                

TRMLFTCHR   VAR(&CHAR10) TRMCHR(* ' ')                               

            ALLTRMCHR(X)                                             

:exmp.                                                                

:p.This command will trim all leading blanks and asterisks from the  

CL variable &CHAR10 and return the remaining characters left adjusted.

If only blanks and asterisks are found in the &CHAR10 variable then  

the left adjusted value 'X' is to be returned.                       

:ehelp.                                                              

As with the help modules for TRMCHR and ALLTRMCHR, you should recognize most of the tags being used by the preceding help module. The one new set of tags is :xmp and :exmp, indicating the start and end of an example. The xmp tag, for the most part, disables the formatting normally done by UIM—for instance, the concatenation of text from one source line to the next, trimming trailing blanks. There are a few exceptions related to the available width of the help display area, but in general the xmp tag provides a "what you see is what you get" environment for demonstrating command inputs and resulting outputs.

The last help module that is provided by the GENCMDDOC command is related to the possible escape, status, and notify messages that might be sent by the TRMLFTCHR CPP—that is, the messages that your CL program using the TRMLFTCHR command can monitor for with the MONMSG command. Currently, no messages are sent by the CPP. But rather than assume the CPP is perfect, we'll add a program-level monitor to the CPP and send the escape message TRM0009 in the event the monitor is run. To add message description TRM0009 to the VINING/USERMSGF message file, you can use the following command.

ADDMSGD MSGID(TRM0009) MSGF(VINING/USERMSGF) +

MSG('Unexpected error. See job log for additional information.')

To send the message from the CPP, we will also make these changes to the TRMLFTCHR CL program:

• Add a program-level monitor after the last DCL command:

                MonMsg MsgID(CPF0000 MCH0000) Exec(GoTo CmdLbl(Error))

• Add the following commands prior to the ENDPGM command:

                                Return

      Error:

            SndPgmMsg  MsgID(TRM0009) MsgF(Vining/UserMsgf) +

                         MsgType(*Escape)

And then recompile the program with either

CRTBNDCL PGM(TRMLFTCHR)

or

CRTCLPGM PGM(TRMLFTCHR)

With these changes out of the way, we're now ready to work on the error message help module. As with the example help module, you should recognize many of the tags you find in the error message help module. You should also see that a new feature of the &msg symbol is being introduced. In the previous help modules, the msg symbol was referencing message descriptions that could be found in the USERMSGF message file. As this message file was earlier designated as the default message file for msg symbols with the submsgf attribute of the pnlgrp tag, there was no need for us to re-specify the message file. In the error message help module, though, we're referencing two IBM-provided message descriptions: CPX0005 and CPX0006. The new attribute specifies where these message descriptions can be found—in this case, the message file QCPFMSG.

There are also new tags found in the error message help module, though you can probably guess the purpose of these tags due to your earlier exposure to similar tags. The dl tag starts a list of definitions, the dt tag a definition term, the dd tag a definition description, and the edl tag the end of the definition list. The term being defined is the message ID that can be sent, and the description is the first-level text of the message. Associated with the dl tag is the attribute COMPACT. Lists default to having one blank line between each list item. The compact attribute causes the list to be formatted without the blank line between items and is supported with the ol and ul tags in addition to the dl tag.

The GENCMDDOC command generates several IBM-provided error messages in the definition list. As the TRMLFTCHR command will not send any of these messages, we should remove them. But prior to deleting these IBM-provided messages from the panel group source, note that a fourth attribute of the msg symbol, nosub, has been specified (there is also a new third attribute, but I suspect it's intended use can be easily guessed at). The first-level text of many error messages includes replacement text variables (&1, &2, etc). By default, the msg symbol will substitute blanks for the replacement text variables. That is, &msg(CPF9801,QCPFMSG). will generate the help text 'Object  in library  not found.' in our help panel group. The nosub attribute causes the replacement text variables to not be substituted, which I generally find more useful within help text. That is, &msg(CPF9801,QCPFMSG,*LIBL,nosub). will generate the help text 'Object &2 in library &3 not found.' In the case of TRMLFTCHR, none of our TRM* messages utilize replacement variables in the first-level text, so we can simply go with the default value.

After removing the GENCMDDOC-generated dt and dd tags, we'll add one entry for the TRM0009 error message we previously defined. The following help module source demonstrates our changes.

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

.*                                                                    

.* Error messages for TRMLFTCHR                                       

.*                                                                    

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

:help name='TRMLFTCHR/ERROR/MESSAGES'.                                

&msg(CPX0005,QCPFMSG). TRMLFTCHR - Help                               

:xh3.&msg(CPX0005,QCPFMSG). TRMLFTCHR                                  

:p.:hp3.*ESCAPE &msg(CPX0006,QCPFMSG).:ehp3.                          

:DL COMPACT.

:DT.TRM0009                                           

:DD.&MSG(TRM0009).              

:EDL.                                                                  

:ehelp.                                                               

:epnlgrp.                                                             

That completes our general updates of the TRMLFTCHR command help text. If you would like to see the command help text as it stands with the changes made in this article, you can re-create the panel group with this command:

CRTPNLGRP PNLGRP(TRMLFTCHR)

Once created, you can then prompt the TRMLFTCHR command and request help with F1 followed by F2 to access the extended help.

As you will hopefully agree, providing and maintaining help text for commands does not take much time or effort. And the productivity advantage in having help directly associated with the command—as opposed to having to run off to some book that may or may not be up to date (or easily found for that matter)—leads me to the conclusion that any command without help text is a command that is only half done. There is one problem, though, with having help text associated with the command itself—namely, that you need access to an i in order to prompt the command and then read the help text. Wouldn't it be nice to also provide the help text on the Web and in hardcopy? Next month, we'll see how to provide the command help text on a Web site and explore a few other items that are easily implemented.

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.

 as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7,

Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at This email address is being protected from spambots. You need JavaScript enabled to view it.. 

---

MC Press books written by Bruce Vining available now on the MC Press Bookstore.

		IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale

Also Read

TechTip: Printing from a CL Program (the PRTLN Command)

TechTip: Date Arithmetic in CL Programs

TechTip: Entering Quotes in CL Variables — A Better Way?