Generate A HelpText Panel Template for any Command

You've seen IBM CL command, such as CPY (copy file) or CRTBNDRPG (Create Bound RPG IV) that when prompted, enable the F1=Help key, right? The source code used to create command help pre-dates HTML. In fact, some components of HTML (I'm speculating) were influenced by it. Command help is created using a little-known UIM language. UIM was developed during the DCA (Document Content Architecture) era and shares some syntax with other things built during the period of history.

Today IBM would do well by simply replacing UIM with HTML, so it could actually be used used by customers. In fact, they currently generate HTML when you prompt a CL command from within RDp and press Help. They use an API that is the same API used by the obscure and largely unknown command named GENCMDDOC (Generate Command Documentation) which is IBM's even more obscure way of saying "Generate Help Text source code for a CL command".

The GENCMDDOC command will generate either UIM or HTML for a command, in "command helptext format". This mean you can generate a template of helptext for your user-written CL commands, and then go in with the EDTF command and modify it. Yes, the GENCMDDOC command only writes to the IFS. To move the generated source into a real source file member, use the CPYFRMSTMF command.

UIM (User Interface Manager)

The User Interface Manager or UIM (read more on IBM.com) is really an alternative to DDS for Display Files. If I'm not certain, however I think IBM uses UIM for all of its displays (vs using DDS). So things like WRKSPLF are using UIM instead of classic DDS.

While UIM has always been interesting, relatively few customers have actually used it in production. There are several IBM i "personalities" have created tools (free or otherwise) that utilize UIM for subfiles and other displays, but other than that, it was largely an IBM-only tool.

I have little use for learning UIM today--but with the COZTOOLS including so many commands, it was only a matter of time before people started asking me for Command Prompter Helptext (Thanks Mark!). So I stumbled upon GENCMDDOC to generate the UIM template which allowed me to fill in the missing helptext much more easily than writing it from scratch.  

 

Generate Command Documentation (GENCMDDOC)

This command retrieves either HTML or UIM source from an existing *CMD object ("Command Definition"). If HTML is generated, it is nicely formatted HTML that can be used as online helptext for the command. For example, we are now using this to generated the online help published on the COZTOOLS.com website.

If UIM is generated, it uses only the command definition to build UIM source that can be further updated and used as the F1=Help helptext for the command. It is up to you to go into that generated UIM and add the helptext. Once the helptext is complete, you have to compile the UIM source. UIM source does not create a UIM object; instead it is used to create a Panel Group (*PNLGRP) object. That panel group can be associated with anything, but it typically associated with the original command definition as helptext.

To compile UIM source into a panel group object, use the CRTPNLGRP command. Oh wait, CRTPNLGRP only reads from real source file members, so the IFS file containing the UIM source is useless. Nicely done IBM!

To fix this goofy design, you have to copy the UIM source from the IFS to a real source file member. I use CPYFRMSTMF to do that but you can do it anyway you wish.

CHGCMD (Change Command)

The CHGCMD command can be used to assign the UIM Panel Group to the command itself. The HLPPNLGRP and HLPID parameters of the CHGCMD (or CRTCMD) command are used to assign the helptext to the command. For example, to change the CLSCAN command so that it includes the helptext I recently created, I would run the following CHGCMD command:

 CHGCMD CMD(COZTOOLS/CLSCAN) +
         HLPPNLGRP(COZTOOLS/CLSCAN) HLPID(*CMD)

This assumes you previously copied the CLSCAN source from the IFS to the QPNLSRC file and then used CRTPNLGRP to compile it.

Build Help to the Rescue

Maybe I'm missing something, but why the GENCMDDOC doesn't reroute to a source file member is strange. So I wrote a helper command to help you create helptext (yes I'm being purposely redundant this week).

Here's my version of the BLDHELP command, prompted for your enjoyment:

The BLDHELP command using GENCMDDOC to extract the UIM helptext template to the IFS. Then it copies that UIM stream file to the source file member you've specified. Optionally, it can assign the UIM Panel Group to the command definition object for you.

Here's the source for BLDHELP:

BLDHELP (Build UIM-Based Command Helptext Panel Group) Command Source

 BLDHELP:    CMD        PROMPT('Build COZTOOLS Tool Help')
             PARM       KWD(CMD) TYPE(QUAL1) MIN(1) PROMPT('Command +
                          name')
             PARM       KWD(DIR) TYPE(*PNAME) LEN(640) +
                          DFT('/coztools/help') EXPR(*YES) +
                          PROMPT('IFS Dir for temp help panel')
             PARM       KWD(SRCFILE) TYPE(QUAL2) MIN(1) PROMPT('Help +
                          UIM/Panel Source file')
             PARM       KWD(SRCMBR) TYPE(*NAME) DFT(*CMD) +
                          SPCVAL((*CMD)) EXPR(*YES) PROMPT('Help +
                          Panel Source member')
             PARM       KWD(CHGCMDHLP) TYPE(*LGL) DFT(*NO) RSTD(*YES) +
                          SPCVAL((*NO '0') (*YES '1')) EXPR(*YES) +
                          PROMPT('Add Help Panel to existing cmd')
 QUAL1:      QUAL       TYPE(*NAME) LEN(10) MIN(1) EXPR(*YES)
             QUAL       TYPE(*NAME) DFT(*LIBL) SPCVAL((*CURLIB) +
                          (*LIBL)) EXPR(*YES) PROMPT('Library')
 QUAL2:      QUAL       TYPE(*NAME) LEN(10) DFT(QPNLSRC) EXPR(*YES)
             QUAL       TYPE(*NAME) DFT(*LIBL) SPCVAL((*CURLIB) +
                          (*LIBL)) EXPR(*YES) PROMPT('Library') 

CL Source for BLDHELP Command

 BLDHELP:    PGM        PARM(&CMD &DIR &SRCF &SRCMBR &ADDCMDHELP)
             DCL        VAR(&CMD) TYPE(*CHAR) LEN(20)
             DCL        VAR(&CMDNAME) TYPE(*CHAR) STG(*DEFINED) +
                          LEN(10) DEFVAR(&CMD 1)
             DCL        VAR(&CMDLIB)  TYPE(*CHAR) STG(*DEFINED) +
                          LEN(10) DEFVAR(&CMD 11)
             DCL        VAR(&DIR)  TYPE(*CHAR) LEN(640)
             DCL        VAR(&TEXT) TYPE(*CHAR) LEN(50)
             DCL        VAR(&STMF) TYPE(*CHAR) LEN(640)
             DCL        VAR(&PNLMBR) TYPE(*CHAR) LEN(640)
             DCL        VAR(&SRCF)    TYPE(*CHAR) LEN(20)
             DCL        VAR(&SRCFILE) TYPE(*CHAR) STG(*DEFINED) +
                          LEN(10) DEFVAR(&SRCF 1)
             DCL        VAR(&SRCLIB)  TYPE(*CHAR) STG(*DEFINED) +
                          LEN(10) DEFVAR(&SRCF 11)
             DCL        VAR(&SRCMBR)  TYPE(*CHAR) LEN(10)
             DCL        VAR(&ADDCMDHELP) TYPE(*LGL) LEN(1)
             MONMSG     MSGID(CPF0000)

             IF         COND(&SRCMBR = '*CMD') THEN(DO)
                CHGVAR     VAR(&SRCMBR) VALUE(&CMDNAME)
             ENDDO
             RTVOBJD    OBJ(&CMDLIB/&CMDNAME) OBJTYPE(*CMD) +
                          RTNLIB(&CMDLIB) TEXT(&TEXT)
             RTVOBJD    OBJ(&SRCLIB/&SRCFILE) OBJTYPE(*FILE) +
                          RTNLIB(&SRCLIB)

             GENCMDDOC  CMD(&CMDLIB/&CMDNAME) TODIR(&DIR) GENOPT(*UIM)
             CHGVAR     VAR(&STMF) VALUE(&DIR *TCAT '/' *CAT &CMDLIB +
                          *TCAT '_' *CAT &CMDNAME *TCAT '.UIM')
             CHGVAR     VAR(&PNLMBR) VALUE('/QSYS.LIB/' *CAT &SRCLIB +
                          *TCAT '.LIB/' *CAT &SRCFILE *TCAT '.FILE/' +
                          *CAT &SRCMBR *TCAT '.MBR')
             CPYFRMSTMF FROMSTMF(&STMF) TOMBR(&PNLMBR)

             CHGPFM     FILE(&SRCLIB/&SRCFILE) MBR(&SRCMBR) +
                          SRCTYPE(PNLGRP) TEXT(&TEXT)
             IF (&ADDCMDHELP = '1') THEN(DO)
                CHGCMD     CMD(&CMDLIB/&CMDNAME) +
                             HLPPNLGRP(&CMDNAME/&CMDNAME) HLPID(*CMD)
             ENDDO
 ENDPGM:     ENDPGM 

If we run BLDHELP on the BLDHELP command itself (so we can create helptext for the BLDHELP command) we would see the following:

.*******************************************                            
.*   Help for parameter CMD                                             
.*******************************************                            
:help name='BLDHELP/CMD'.                                               
Command name (CMD) - Help                                               
:xh3.Command name (CMD)                                                 
:p.Specifies <...>                                                      
.* Describe the function provided by the parameter.                     
:p.This is a required parameter.                                        
:p.:hp2.Qualifier 1: Command name:ehp2.                                 
:parml.                                                                 
:pt.:pv.name:epv.                                                       
:pd.                                                                    
Specify the name of <...>                                               
.* Describe the function provided by the user-defined parameter value.  
:eparml.                                                                
:p.:hp2.Qualifier 2: Library:ehp2.                                      
:parml.                                                                 

This is just an excerpt of what we get from GENCMDDOC and therefore from BLDHELP. The areas marked with <...> are for you to insert your helptext. Once finished modifying it, run the CRTPNLGRP command over this source member to compile it. Then use the CHGCMD or CRTCMD and modify the HLPPNLGRP parameter.

Modified UIM Source (Segment)

Once modified, the CMD parameter of the BLDHELP Panel Group source might look like the following:

.*******************************************                            
.*   Help for parameter CMD                                             
.*******************************************                            
:help name='BLDHELP/CMD'.                                               
Command name (CMD) - Help                                               
:xh3.Command name (CMD)                                                 
:p.Specify the name of an existing *CMD object whose helptext           
template is generated.                                                  
.* Describe the function provided by the parameter.                     
:p.This is a required parameter.                                        
:p.:hp2.Qualifier 1: Command name:ehp2.                                 
:parml.                                                                 
:pt.:pv.name:epv.                                                       
:pd.                                                                    
Specify the name of an existing *CMD object.                            
.* Describe the function provided by the user-defined parameter value.  
:eparml.                                                                
:p.:hp2.Qualifier 2: Library:ehp2.                                      
:parml.                                                                 
:pt.:pk.*CURLIB:epk.
:pd. 
Uses the CURRENT LIBARY (*CURLIB) to search for the *CMD object. 
.* Describe the function provided by the pre-defined parameter value. 
:pt.:pk def.*LIBL:epk. 
:pd. 
Uses the LIBARARY LIST (*LIBL) to search for the *CMD object. 
.* Describe the function provided by the pre-defined parameter value. 
:pt.:pv.name:epv. 
:pd. 
Uses a qualified command to the library name specified. 
.* Describe the function provided by the user-defined parameter value.
:eparml. 
:ehelp. 

Next run the CRTPNLGRP command:

CRTPNLGRP PNLGRP(COZTOOLS/BLDHELP) SRCFILE(COZTOOLS/QPNLSRC) 

Now when the BLDHELP command is prompted, press F1 while the cursor is in the CMD parameter produces the following helptext panel:

Conclusions

I love how GENCMDDOC can create HTML that is nicely formatted. While the UIM syntax is a bit dated and should be replaced with strictly HTML (or better yet, XML) it is a workable solution for now. So today, as my buddy Mark told me, there is no real reason to NOT have command definition helptext included in your own CL commands. 

That's all there is to it.

Cozzi Tools - Now Available

Cozzi Tools  is now available at www.cozTools.com Use the same functions to build your own applications that I use in mine. If your company is having financial challenges, download and abuse the free runtime library of CL commands and upgrade to the paid/supported version later. Visit the COZTOOLS website for the latest information; and remember to tell your friends.

Call Me

Bob Cozzi is a technical advisor to IBM i clients around the world. His specialty is solving difficult problems for his clients, training their programming staffs, and performing system migration/upgrades for small shops. His consulting rates are available online. To contact Bob, send an email to: bob at rpgworld.com

You can subscribe to RPG Report (we call it "follow") by visiting the RPG Report page on midrangeNews.com and then click the FOLLOW link in the table of contents for that page. To unsubscribe, simply click that same link. You must be signed up and signed in to midrangeNews.com to start following RPG Report.

Follow Bob Cozzi on Twitter