MC Press Online

'No Sweat' Command Help

Contributed by MC Press Contributing Author Thursday, 31 August 2000 Last Updated Wednesday, 30 July 2008

Writing command help text is unbelievably easy, thanks to this utility.

Programmers and operators alike find OS/400 commands everywhere. Each OS/400 command has built-in help text that you can invoke with a press of the F1 or Help key. This help text provides useful information about the purpose of the command.

However, not everything is an OS/400 command, so OS/400 lets you create your own commands—as I have been doing for many years. These user-defined commands work exactly like IBM’s, except that they have no help text (at least not until you create it manually). The problem is that command help text must be defined in panel group objects (type *PNLGRP), which use the cryptic and, if I may say so, downright ugly User Interface Manager (UIM) language. Therefore, you won’t have any trouble believing me, when I tell you that writing command help text is quite a chore. Unless you do it every day, you’re bound to forget some UIM syntax and end up with compiler error messages left and right. That’s why I created the Create Command Help (CRTCMDHLP) command. Meet CRTCMDHLP

CRTCMDHLP takes the source code of a command you have already written and writes UIM source for the help text. All you need to do is identify, by name, the source file and member of the command source and the source file and member to which you want CRTCMDHLP to write the generated UIM code. CRTCMDHLP creates skeleton help text with all the basic UIM statements. All that’s left is for you to insert the actual help text. Figure 1 shows the output that CRTCMDHLP produces.

As you can see in Figure 1, I had CRTCMDHLP create a skeleton help text member for a command named Indent RPG (INDRPG), which was published in “The Eagle Eye of INDRPG” in the June 1999 issue of MC. All you have to do is replace all occurrences of the (Enter text here) marker with actual text, using the :P. tag to mark the beginning of each paragraph. How It Works

The CRTCMDHLP utility consists of three objects—the CRTCMDHLP command, CL program CRTCMDHLPC, and RPG IV program CRTCMDHLPR. (The source code for these objects can be downloaded from the MC Web site at

www.midrangecomputing.com/mc.) The first two objects are unremarkable, so I won’t waste your time going through them. However, you do need to know that the CL program uses the Forward Program Messages (FWDPGMMSG) utility command, which I wrote for “How to Forward Messages in CL” in the January 1998 issue of MC. (You can also download the command from the MC Web site.)
http://www.mcpressonline.com Powered by Joomla! Generated: 28 September, 2008, 23:50

MC Press Online

The action takes place in the RPG IV program. I’m going to explain CRTCMDHLPR’s workings to you. Perhaps you’ll find a useful coding technique that you can use later in your own projects.

The mainline calculates today’s date and stores that in the today variable, which is defined as a zoned decimal with six digits and zero decimal places. Since I’m using program-described files for simplicity, all output is produced by EXCEPT operations. The mainline also writes the PNLGRP tag (which must be at the very top of the UIM source member) and then reads the command source member record by record. Finally, the mainline writes the EPNLGRP tag, which must be in the last line of the UIM member.

The mainline calls the bld_stmt subroutine, which builds each multiline statement as found in the command source member. CMD code, like CLP code, can contain statements that span multiple lines, so I build each statement in the stmt variable by simply reading records until I find one in which the last nonblank character is neither a plus (+) nor a minus (-) sign. As you’ll recall, either symbol means that the following line of code contains a continuation of the current statement.

I make extensive use of the %TRIM() built-in function to remove leading and trailing blanks. In many cases, I embed this function within %LEN() to calculate the effective length of a character string. For example, if the stmt variable (which is defined as a 6,000-byte alphanumeric variable) contained the first three letters of the alphabet, %LEN(stmt) would yield 6,000. To find that effective length of 3 (the used up portion of the string), I would code %LEN(%TRIM(stmt)). %LEN() is a fairly recent built-in function. If you don’t have it, you can use the CHECKR op code, using a one-space literal in factor 1, a stmt in factor 2, and the field that is to contain the length in the Result field.

Each time the program runs the bld_stmt subroutine, it also runs the process subroutine from within. The latter subroutine actually processes the statement just built. It finds out whether the statement is a CMD or a PARM statement, and that’s all. The process subroutine extracts the first four characters of the statement and runs proc_cmd or proc_parm, depending on the value of those first four characters. The statement identifier could be in uppercase letters, lowercase letters, or any wild combination of uppercase and lowercase letters. To decrease the number of tests, I simply turn those first four characters (stored in stmt_type), as well as the entire statement, into all uppercase, storing the statement in a different variable, stmt_u. Processing the CMD Statement

If process finds a CMD statement, it runs proc_cmd to process it. Now, the CMD statement has only one parameter, PROMPT. The keyword PROMPT, however, is optional; you can code either CMD PROMPT(‘command’) or CMD ‘command’. Both are valid, so proc_cmd must make allowances for either. The first thing proc_cmd does is to find out whether or not a PROMPT( string is anywhere in the statement. I scan for this string in stmt_u (the uppercase version of the statement), so I don’t have to look for PROMPT, prompt, ProMpt, or whatever else may have been coded. I use the %SCAN() built-in function to search for the PROMPT( string. Again, this is a fairly new function. If you don’t have it available, you can use the SCAN op code. Either way, if the string isn’t there, you’ll get either a zero or a positive number indicating where it was found.

In the middle of proc_cmd, an EVAL op code builds a string in the helptag variable, which is later used by one of the EXCEPT op codes within the same subroutine to write the :HELP. tag, which marks the beginning of the help text for the entire command (what’s called “extended” help). Four EVAL/EXCEPT pairs write UIM code containing the
http://www.mcpressonline.com Powered by Joomla! Generated: 28 September, 2008, 23:50

MC Press Online

:HELP. tag, the :P. tag, the text (Enter text here), and the :EHELP. tag. Control then returns to process. Processing the PARM Statement

The PARM statement is much more complicated and requires a somewhat more elaborate subroutine, proc_parm. Fortunately, however, you’re interested in only two portions of the PARM statement: the name of the parameter as identified by the KWD() keyword and the text description of the parameter as identified by the PROMPT() keyword. KWD() may be there or may be missing, so proc_parm begins by searching for the KWD( string within stmt_u. It then extracts the name of the parameter, stores it in parmname, and uses this value to build the :HELP. tag for the parameter. Immediately after that, proc_parm extracts the text description from the PROMPT() keyword, which fortunately cannot be omitted from the source code you’re reading. This means that you can look for the PROMPT( string and then extract the text description and store it in title. Six EVAL/EXCEPT pairs will write UIM code for the PARM statement, and you’re done. Your Mission: Enhancements

I hope you find time to enhance CRTCMDHLP. Here are two ideas for doing so. The PROMPT() keyword and its value can be entirely missing in both the CMD and the PARM statements. The tool has no provision for a missing PROMPT(), because it seemed to me that this keyword would be there in the vast majority of cases.

PARMs can have lists of valid values in either the VALUES() keyword or the SPCVAL() keyword. The proc_parm subroutine can be expanded to analyze these keywords, which must always have the VALUES( or SPCVAL( string, to embed :DL./:DT./:DD./:EDL. tag groups listing these values. For example, if you write a command that needs an OUTPUT parameter and the parameter accepts only * and *PRINT, you can code the command as follows:

PARM output *CHAR 6 +

RSTD(*YES) +

VALUES(* *PRINT) +

PROMPT(‘Output’)

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 September, 2008, 23:50

MC Press Online

It would be nice if CRTCMDHLP wrote the UIM code necessary to list these special values when the user pressed the Help key. UIM requires the syntax in Figure 2.

The interesting part occurs between the :DL. and :EDL. tags, both inclusive. They bracket pairs of :DT. and :DD. tags, each pair defining one special value. The first tag of the pair (:DT.) shows the special value itself; the second tag (:DD.) bears a description or an explanation of that special value.

Help text makes an application much easier to use. CRTCMDHLP makes help text easier to write. Put CRTCMDHLP to work in your shop.

:PNLGRP. :HELP NAME=INDRPG. :P. (Enter text here) :EHELP. :HELP NAME=INDRPG/SRCFILE. Src file, program, or module (SRCFILE) :XH3.Src file, program, or module (SRCFILE) :P. (Enter text here) :EHELP. :HELP NAME=INDRPG/SRCMBR. Source member (SRCMBR) :XH3.Source member (SRCMBR) :P. (Enter text here)

:EHELP. :EPNLGRP. :HELP NAME='XXX/OUTPUT'.

http://www.mcpressonline.com Powered by Joomla! Generated: 28 September, 2008, 23:50

MC Press Online

Output (OUTPUT) :XH3.Output (OUTPUT) :P. Type the special value * or *PRINT, depending on where you want the output: :DL. :DT.* :DD.Output goes to the display. :DT.*PRINT :DD.Output goes to the printer. :EDL. :EHELP.

Figure 1: CRTCMDHLP creates a useful help text skeleton; all you have to do is insert the actual help text.

Figure 2: This is the UIM code required for lists of values.

http://www.mcpressonline.com

Powered by Joomla!

Generated: 28 September, 2008, 23:50