Generate UIM source for command help

As a simpler alternative to learning UIM syntax, you can use the Generate Command Documentation (GENCMDDOC) command. This command allows you to create a file containing UIM source; the file provides a template for the online command help. To create the UIM source, you need to specify *UIM for the GENOPT (Generation Options) parameter. The information used to create the template is retrieved from the command object (*CMD) you specify. Using Generate Command Documentation (GENCMDDOC) to create the UIM source can simplify writing online help for your CL commands.

The following is an example of using the Generate Command Documentation (GENCMDDOC) command to generate a UIM template:

GENCMDDOC   CMD(MYLIB/MYCMD)
            TODIR('/QSYS.LIB/MYLIB.LIB/QPNLSRC.FILE')
            TOSTMF(*CMD)  GENOPT(*UIM)

In the example, the command retrieves information from the command object named MYCMD in library MYLIB and generates UIM source into member MYCMD of source file QPNLSRC in library MYLIB. After the template UIM source has been generated, you will need to edit the UIM source as follows:

• Ensure that the command-level help module describes the purpose of the command. The start of the first sentence is provided followed by a <...> marker that you need to replace with the appropriate text. Ensure that restrictions that apply to running the command are described, such as commands that must be run first, or special authorizations needed. Some example restrictions are provided; you should edit these to match your command's restrictions.
• Ensure that each parameter-level help module explains the purpose of the parameter. The start of the first sentence is provided followed by a <...> marker that you need to replace with the appropriate text. You may also want to describe any inter-parameter dependencies or restrictions; you can use the :NT. (Note) and :ENT. (End of Note) UIM tags for these parameter-level restrictions.

  The parameter-level help module also should provide a description of the possible choices for the parameter. Headings for each special value or single value are provided, but you need to replace the <...> markers with the parameter value descriptions.

• Ensure that examples are provided as needed. The command examples help module is primed with headings for two examples. If the command has no parameters, you could edit this help module to have only a single example. If the command has many parameters, or provides several distinct functions, you can copy the headings to create additional command examples. You need to edit the command examples to insert your own commands' parameter keywords and parameter values and to replace the <...> markers with the descriptions of what the example commands would do.
• Ensure that error message text is provided as needed. The command error messages help module is primed with headings showing how you can use the &MSG. built-in function to imbed the message text of error messages sent by the command. You need to edit the list of messages to contain the actual message identifiers of messages signaled from your command, along with the message file that contains the message descriptions.

Once you've edited the UIM source to tailor it to your command, you can create the online help panel group by using the Create Panel Group (CRTPNLGRP) command. The following is an example of using the Create Panel Group (CRTPNLGRP) command:

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

This command attempts to create a panel group from the UIM source in member MYCMD in source physical file QPNLSRC in library MYLIB. If there are no severe errors found when compiling the UIM source, a panel group (*PNLGRP) object named MYCMD is created in library MYCMD. The command generates a spooled file, which can be viewed to see informational, warning, and severe errors found by the UIM compiler.