In this installment of APIs by Example, Carsten Flensburg has written a useful utility to generate help for your commands.

When you run this utility, you give it the source member of a command that you've written. It will parse your command source and generate some panel groups to be used as help screens for your command.

A CL program has been provided to create the message files and compile the programs needed to run this utility. To build the utility, run the following commands:

    CRTCLPGM PGM(CBX113C) SRCFILE(mylib/QCLSRC)
    CALL PGM(CBX113C) PARM(mylib)

To run the utility, execute the GENCMDHLP command. Here's what the command looks like when prompted:

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

                       Generate Command Help (GENCMDHLP)              
Type choices, press Enter.                                            
Command source file  . . . . . .                 Name                 
  Library  . . . . . . . . . . .     *LIBL       Name, *LIBL, *CURLIB 
Command source member  . . . . .                 Name                 
Panel group source file  . . . .   QPNLSRC       Name, QPNLSRC        
  Library  . . . . . . . . . . .     *LIBL       Name, *LIBL, *CURLIB 
Panel group source member  . . .   *FROMMBR      Name, *FROMMBR       
Allow replace of to member . . .   *NO           *NO, *YES            
Help identifier  . . . . . . . .   *CMD          Character value, 
*CMD

= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =

Here's an overview of how to use the GENCMDHLP utility:

1. First, create the command source for the command that you're developing. In this example, we'll say that the command is called "DSPORD."



2. Run the GENCMDHLP utility to generate the command help.

   GENCMDHLP FROMFILE(mylib/QCMDSRC) FROMMBR(DSPORD) 
   TOFILE(mylib/QPNLSRC) 

3. Edit the generated source for your help panels. The source will be in the source member indicated by the TOFILE parameter of GENCMDHLP. Insert the command's documentation where it says "Insert help text here."
   
   
4. Compile the panel group for your command.

   CRTPNLGRP PNLGRP(mylib/DSPORD) SRCFILE(mylib/QPNLSRC)

5. Reference the compiled panel group when creating your command:

   CRTCMD CMD(DSPORD) PGM(myCPP) SRCFILE(mylib/QCMDSRC)
           HLPPNLGRP(mylib/DSPORD) HLPID(*CMD) 

The following APIs are demonstrated in the GENCMDHLP utility:

Move Program Messages (QMHMOVPM)
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/qmhmovpm.htm

Resend Escape Message (QMHRSNEM)
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QMHRSNEM.htm

Send Program Message (QMHSNDPM)
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QMHSNDPM.htm

Retrieve Message (QMHRTVM)
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QMHRTVM.htm

Process Commands (QCAPCMD)
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/qcapcmd.htm

Convert Case (QlgConvertCase)
http://publib.boulder.ibm.com/iseries/v5r2/ic2924/info/apis/QLGCNVCS.htm

You can retrieve the source code for this utility from
http://www.iseriesnetwork.com/noderesources/code/clubtechcode/GenCmdHlp.zip

The above source code was written by Carsten Flensburg. For questions regarding this tip, contact Carsten at mailto:flensburg@novasol.dk