APIs by Example: Do You Need Help?

By:

Getting help exactly where and when you need it certainly increases the value of the help you get. And as a programmer, you can add value to the commands and utilities you write by providing online help, which in turn gives your users a fair chance to both fully exploit and correctly use the outcome of your efforts.

Today's APIs by Example is about both getting and providing help in a useful and timely fashion. I provide two new CL commands that will help you get at the information you need for your daily programming tasks and successfully help your users.

As for the "getting help" part, IBM, up to V4R4, published a comprehensive yet compact manual called the Programming Reference Summary. In it, you can find a wealth of information dealing with all kinds of documentation that a programmer would need and seek on a daily basis. You can find links to the final version of the Programming Reference Summary manual at the end of the article.

I also provide links to the V4R5-and-later releases documentation that show where you can find the different parts of this collection in case you want to have a look for yourself. Please note that for some reason the hint of what happened to Chapter 16: UIM Tags and Dialog Commands never made it online — you can search for this in the Application Display Programming manual.

One often-sought chapter of this manual was Chapter 8: Error Messages that Can Be Monitored. This chapter lists all *ESCAPE, *STATUS and *NOTIFY messages that could be signaled from a CL command to the program running the command. This kind of information is of course important knowledge in trying to make your CL programs robust and capable of handling the possible exceptions that might occur when executing a command.

The last time the full list of monitorable messages was actually included in the Programming Reference Summary was in the V4R1 edition (see link below). As of V4R2, IBM made this information part of each individual CL command’s online help text. This ensures that the message list is immediately available to you, the programmer. However, you have to page down a number of times to actually arrive at the information because it is at the very end of the command help text — for example, you have to press the page down button 15 times to get to the Check Object (CHKOBJ) command's list of messages:


                            Check Object - Help                            
      have data authority for FILEA and each of the physical file members  
      on which FILEA is based, escape message CPF9802 is sent to the       
      program, and control in the program is passed to the command that    
      has the label ERROR1.                                                
  Error messages for CHKOBJ                                                
      *ESCAPE Messages                                                     
      CPF9801     Object &2 in library &3 not found.                       
      CPF9802     Not authorized to object &2 in &3.                       
      CPF9810     Library &1 not found.                                    
      CPF9815     Member &5 file &2 in library &3 not found.               
      CPF9820     Not authorized to use library &1.                        
      CPF9830     Cannot assign library &1.                                
      CPF9899     Error occurred during processing of command.             
                                                                    Bottom 
  F3=Exit help   F10=Move to top   F12=Cancel   F13=Information Assistant  
  F14=Print help

To speed up the process and make the error message list immediately accessible, I've taken advantage of a couple of the User Interface Manager (UIM) APIs that let you display and print one or more sections of a help panel group. A help panel group contains various specific sections of help text. For example, as of V5R3 you'll find the following sections for a native i5/OS command:

Global help-text section describing the purpose of the command and specific restrictions applying to the use of the command.
Parameter-specific help-text section for each of the command's keywords describing the use of the parameter as well as an optional list of the possible values to specify as input to the parameter.
An example section offering one or more command examples specifying how to use the command to perform various tasks and what the outcome will be for each of the specified examples.
A monitorable messages section listing all the error messages that you can monitor for in a CL program.

The name (i.e.,the help ID), of each of these sections follows a standard naming scheme, which lets you figure out what to specify as input to the UIM Display Help or Print Help APIs — together, these play the leading role in the Display Command Help (DSPCMDHLP) command processing program (CPP). Here's what the command prompt looks like:


                        Display Command Help (DSPCMDHLP)                   
 Type choices, press Enter.                                                
 Command  . . . . . . . . . . . .                 Name                     
   Library  . . . . . . . . . . .     *LIBL       Name, *LIBL, *CURLIB     
 Select . . . . . . . . . . . . .   *MONMSG       *MONMSG, *CMDLVL, *CMD...  
 Display option . . . . . . . . .   *FULL         *FULL, *WDW              
 Output . . . . . . . . . . . . .   *             *, *PRINT

The DSPCMDHLP command lets you specify a number of special values, each indicating a specific help section:

The *MONMSG special value returns the list of messages that you can monitor. This is the default value.
The *CMD special value returns the global command help text section.
The *EXAMPLES special value returns the command examples section.
The *CMDLVL special value returns all three sections.
The *KWD special value lets you specify a command keyword for which to return the parameter help section.

Now if you run the command DSPCMDHLP CHKOBJ you will see the following display immediately, without exercising your page down finger:


 Help                   Error messages for CHKOBJ - Help               
 Error messages for CHKOBJ                                             
     *ESCAPE Messages                                               
     CPF9801     Object &2 in library &3 not found.                    
     CPF9802     Not authorized to object &2 in &3.                    
     CPF9810     Library &1 not found.                                   
     CPF9815     Member &5 file &2 in library &3 not found.              
     CPF9820     Not authorized to use library &1.                       
     CPF9830     Cannot assign library &1.                               
     CPF9899     Error occurred during processing of command.             
                                                                    Bottom
 F3=Exit help   F10=Move to top   F12=Cancel   F13=Information Assistant   
 F14=Print help

The DSPCMDHLP command includes a help panel group explaining the command and all its parameters in detail. This brings us to the next item on today's agenda, the providing help topic introduced above.

Although IBM always has taken that part seriously, providing help panel groups for their commands and display panels since the first release of OS/400 in 1988, this is surprisingly not always the case for many third-party System i products. One of the reasons for that sad situation could be the challenges involved in creating online help panel groups and the lack of straightforward documentation.

Anyway, at some point I felt overwhelmed by all the repetitious tasks and the volume of typing that I faced every time I wanted to write a help panel group. I decided to write a utility that would create a help panel group source skeleton based on a command definition source. The result was the Generate Command Help (GENCMDHLP) command previously published in this newsletter - APIs By Example: Generate Command Help [2]

Coincidentally, shortly after IBM announced that it would include in V5R3 a Generate Command Documentation (GENCMDDOC) command, offering, among other things, the exact same service as GENCMDHLP. The GENCMDDOC, however, operates based on the command object, using the Retrieve Command Definition (QCDRCMDD) API to extract the command parameter information into an XML document, and XSLT and Java code to parse that document.

Influenced by the affection that writing a utility of your own sometimes creates, I've until now used my GENCMDHLP command when writing help panel groups for the commands and utilities presented in this column. In an e-mail exchange with Guy Vig of IBM some time ago, I was made aware that IBM, with release V5R3, had changed the command help text style and guidelines as part of an attempt to modernize and unify the online command help and the CL Reference manual command documentation, including the new CL command syntax diagrams.

Here are some of the changes introduced in the online command help text style with release V5R3 as Guy very kindly explained:

Added standard headings before parameter qualifiers and elements (e.g. Qualifier 2: Library).
Omitted phrases like 'The possible values are:'from the help text.
Added user-defined choices that reflect the parameter type. For example the previous use of tags like :pv.library-name:epv. was brought in compliance with the new syntax table and is now simply specified as :pv.name:epv.
Added the special command example help section. The naming convention is "<Command-level help ID>/COMMAND/EXAMPLES". The command-level help ID is normally the name of the command object for which the help panel group is created.
Added a new command-error-messages help section. The naming convention is "<Command-level help ID>/ERROR/MESSAGES".

All the guidelines mentioned above are supported by the native GENCMDDOC command. Consequently, I've decided that it is also time for me to take advantage of the GENCMDDOC command for the creation of help panel groups from now on. And I thought I'd take this opportunity to introduce you to the GENCMDDOC command as well, in case you haven't used it until now. There are, however, some issues to take notice of, before going down that road:

Because the GENCMDDOC command spawns a second job that creates a Java Virtual Machine (JVM) for the execution of the XML parsing code, you'll notice a significant delay when you run the GENCMDDOC command.
Because the GENCMDDOC also provides a facility to create the command documentation in HTML and output it to a file in the Integrated File System (IFS), you'll have to specify the command object name and output file member in path name format, which is a little more complex to specify than the simple library/object qualification.
The GENCMDDOC command's resulting error and completion messages are returned to the command processing program (CPP), as opposed to the command caller and are therefore only available in the job log of the job running the command.

To make the change to the GENCMDDOC command a little easier, I've therefore created my own command interface to the GENCMDDOC command, specializing in the creation of a UIM help panel group skeleton for any given command object. This allows me to revert to the library/object qualification as well as add some messaging services to keep the user informed about the process and it's outcome. The command is called Generate UIM Help Source (GENUIMHLP) and has the following appearance when prompted:


                      Generate UIM Help Source (GENUIMHLP)             
 Type choices, press Enter.                                            
 Command  . . . . . . . . . . . .                 Name                 
   Library  . . . . . . . . . . .     *LIBL       Name, *LIBL, *CURLIB 
 Panel group source file  . . . .   QPNLSRC       Name, QPNLSRC        
   Library  . . . . . . . . . . .     *LIBL       Name, *LIBL, *CURLIB     
 Panel group source member  . . .   *CMD          Name, *CMD           
 Allow replace of to member . . .   *NO           *NO, *YES

Because the GENUIMHLP command runs the GENCMDDOC command under the covers, it should be fully forward compatible as long as IBM does not break the GENCMDDOC command's backward compatibility.

I'm running out of space for now, but in a future article I will discuss in more detail how to create help panel groups and the techniques involved in that discipline. Today I'll leave you with a brief walkthrough of how the help panel group for the DSPCMDHLP command was created by means of the GENUIMHLP command. Once you've created both commands in question by following the instructions below, I suggest you do the following to get a picture of the work that the GENCMDDOC command accomplishes, as well as what I had to add to complete the command help text for the DSPCMDHLP command:

Run the GENUIMHLP command against the DSPCMDHLP command object, naming the resulting panel group source member CBX1741H2 and placing it in the same source file as the CBX1741H source member accompanying this article:
```
     GENUIMHLP CMD(DSPCMDHLP)  
               TOFILE(QPNLSRC) 
               TOMBR(CBX1741H2)
               REPLACE(*NO)
```
Run the Compare Physical File Member (CMPPFM) command against the two help panel group sources. This will allow you to view all the skeleton help panel group source changes compared to the complete help panel group source:
```
     CMPPFM    NEWFILE(QPNLSRC) 
               NEWMBR(CBX1741H)           
               OLDFILE(QPNLSRC) 
               OLDMBR(CBX1741H2)
               RPTTYPE(*DETAIL)
```
Browse through the generated report and notice all the lines with line ID "I", which are the lines I have inserted, and all the lines with line ID 'D', which are the lines I have deleted. But as you see, most of the work was done by the GENCMDDOC command.

One final note about linking a help panel group to a command object. This is achieved using the Create Command (CRTCMD) or Change Command (CHGCMD) commands, specifying the Panel group name (HLPPNLGRP) and the Help ID (HLPID) attributes, as in the following example:

  CRTCMD      CMD(DSPCMDHLP)    
              PGM(CBX1741)              
              SRCFILE(QCMDSRC)  
              SRCMBR(CBX1741X)          
              VLDCKR(CBX1741V)          
              HLPPNLGRP(CBX1741H)       
              HLPID(*CMD)

This APIs by Example includes the following sources:

CBX1741  -- RPGLE  -- Display Command Help - CPP     
CBX1741H -- PNLGRP -- Display Command Help - Help    
CBX1741V -- RPGLE  -- Display Command Help - VCP     
CBX1741X -- CMD    -- Display Command Help 
CBX1742  -- CLP    -- Generate UIM Help Source - CPP 
CBX1742H -- PNLGRP -- Generate UIM Help Source - Help
CBX1742V -- RPGLE  -- Generate UIM Help Source - VCP 
CBX1742X -- CMD    -- Generate UIM Help Source       

CBX174M  -- CLP    -- Help Commands - Build commands

To create all above objects, compile and run CBX174M. Compilation instructions are found in the source headers as usual.

IBM Command Help Related Documentation:

Generate Command Documentation command:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/cl/gencmddoc.htm [3]

Generating UIM Source for Command Help:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rbam6/genuim.htm [4]

Writing Command Help:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rbam6/clhelp.htm [5]

Application Display Programming:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rzahg/rzahgapdlprint.htm [6]

Programming Reference Summary V4R1:
http://publib.boulder.ibm.com/pubs/pdfs/as400/V4R1PDF/QB3AUT00.pdf [7]

Programming Reference Summary V4R4:
http://publib.boulder.ibm.com/cgi-bin/bookmgr/DOCNUM/SX41-5720-03 [8] http://publib.boulder.ibm.com/pubs/pdfs/as400/V4R4PDF/QB3AUT03.PDF [9]

Programming Reference Summary V4R5:
http://publib.boulder.ibm.com/pubs/pdfs/as400/V4R5PDF/X4157204.PDF [10]

Obsolete iSeries Manuals V5R4 - Information about the Programming Reference Summary manual:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/topic/rzahg/v5r4infomap.htm#prs [11]

This article demonstrates the following User Interface Manager (UIM) APIs:

Display Help (QUHDSPH) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/quhdsph.htm [12]

Print Help (QUHPRTH) API:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/quhprth.htm [13]

All User Interface Manager (UIM) APIs are documented here:
http://publib.boulder.ibm.com/infocenter/iseries/v5r3/topic/apis/uim1.htm [14]

You can retrieve the source code for this API example from:
http://www.pentontech.com/IBMContent/Documents/article/54890_226_NeedHelp.zip [15]