Easily Create Help Text For Commands

Extending IBM i by writing one’s own commands is empowering and gratifying, but a command without help text is like scrambled eggs without salsa. Fortunately, generating help text for a command is easy, thanks to a technique I learned from a very talented programmer named Chris Wages. Let me show you how it’s done.

First, you must have a command, of course. Here’s the source code for command DOIT.

CMD        PROMPT('Do it')

PARM       KWD(HOW) TYPE(*CHAR) LEN(7) RSTD(*YES) +
             DFT(*WELL) +
             VALUES(*WELL *BETTER *BEST) +
             EXPR(*YES) +
             PROMPT('How should I do it?')

PARM       KWD(WHEN) TYPE(*CHAR) LEN(8) RSTD(*YES) +
             DFT(*MORNING) +
             VALUES(*MORNING *NOON *NIGHT) +
             MAX(3) EXPR(*YES) +
             PROMPT('When should I do it?')

I’ve created the command and tested it, and I know it works properly. Time for help text! Use the Generate Command Documentation (GENCMDDOC) command.

GENCMDDOC CMD(MYLIB/DOIT)
          TODIR('/qsys.lib/mylib.lib/qpnlsrc.file')
          TOSTMF(doit.mbr)
          GENOPT(*UIM)

Notice that the help text is placed into a source physical file called QPNLSRC. Notice also that GENCMDDOC requires the source physical file name and member name to be specified in IFS format.

Change the source type from UIM to PNLGRP.

At this point, I edit the source, numbering all occurrences of the substitution token, <…>. That is, I change the tokens to something like <.1.>, <.2.>, etc. This makes it easy for me to replace each token with the proper text.

Use the Create Panel Group (CRTPNLGRP) to create the panel group object. (This is easily done with option 14 of PDM.)

CRTPNLGRP PNLGRP(MYLIB/DOIT)
          SRCFILE(MYLIB/QPNLSRC)
          SRCMBR(DOIT)

Now it’s time to connect the help text to the command. Notice the HLPPNLGRP and HLPID parameters.

CRTCMD CMD(MYLIB/DOIT)
       PGM(*LIBL/DOIT)
       SRCFILE(MYLIB/SRC)
       SRCMBR(DOIT)
       HLPPNLGRP(DOIT)
       HLPID(*CMD)

At this point, I work with two sessions. In the first one, I prompt the command to view the command text. In the other, I edit the help text source code.

In the first session, I type the command name at a command line, press F4 to prompt, move the cursor up one line to position it in front of the first parameter, and press F1 to bring up the help text. Figure 1 below shows what I see.

Figure 1. (Click graphic to enlarge.)

In the second session, I modify the source code as required, based on what I see in the first session. (This works especially well if you have two monitors!) I delete lines I don’t want and I change the values of substitution tokens, message IDs, etc. I prefer to make a few small mods at a time and rebuild the panel group, rather than trying to build all the help text at one time, just in case I introduce a syntax error. I especially recommend this approach to those who are not proficient with UIM.

When I’ve finished, my help text looks like Figure 2.

Figure 2. (Click graphic to enlarge.)

Let me point out that you do not have to recreate the command when you make a change to the panel group. Every time you press F1 for help, the system will reload the panel group. In fact, you don’t even have to exit to the command line when prompting the command. Just exit the help text, which returns you to the command prompt screen and press F1 once again.

Commands are one of the best–and most underused and unappreciated–features of IBM i. Adding help text is an easy way to improve the usefulness of your commands.

RELATED STORY

Commands: Underused and Unappreciated

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot