Generating help text using an IBM i command

This is another post about something I did not know existed until a few days ago. I have been building some commands to help automate certain processes, and I thought it would be a good idea to create help text for the commands so that anyone using it could use it instead of asking me how to use the command.

Help text for commands must be in the form of a panel group object, *PNLGRP. The programming language used to create the contents of a panel group is User Interface Manager, UIM. Don't worry if you have never used UIM, I think it is a simple language to understand.

Several years ago I wrote a post about creating help panel groups with UIM, therefore, if you want more information than I am going to mention here please refer to that post.

I "stumbled" across the command GENCMDDOC, Generate Command Documentation, which will create a template for my command that I can then add details to. I admit I have never heard of it before, and having used it I found it saved me a lot of time.

First I need a command. I just randomly copied some parts of commands I had created earlier into one new command, TESTCMD.

01 CMD PROMPT('Command example') 02 PARM KWD(FILE) TYPE(Q1) MIN(1) PROMPT('File') 03 Q1: QUAL TYPE(*NAME) LEN(10) MIN(1) 04 QUAL TYPE(*NAME) LEN(10) DFT(*LIBL) SPCVAL((*LIBL)) PROMPT('Library') 05 PARM KWD(SERVER) TYPE(*CHAR) LEN(20) MIN(1) PROMPT('Server') 06 PARM KWD(NUMBER) TYPE(*DEC) LEN(0) RSTD(*YES) DFT(1) + 07 VALUES(0 2 4 6 8) MIN(0) PROMPT('Number') 08 PARM KWD(CATEGORY) TYPE(*CHAR) LEN(10) MIN(1) MAX(10) PROMPT('Categories')

I am not going to create a Command Processing Program, CPP, nor a Validation Checking Program, as this is just to demonstrate what this command does.

I created the command with the following:

CRTCMD CMD(MYLIB/TESTCMD) PGM(CPP_PGM) SRCFILE(DEVSRC)

I can then test the command by typing the following and pressing F4:

Command example (TESTCMD) Type choices, press Enter. File . . . . . . . . . . . . . . Name Library . . . . . . . . . . . *LIBL Name, *LIBL Server . . . . . . . . . . . . . Number . . . . . . . . . . . . . 0 0, 2, 4, 6, 8 Categories . . . . . . . . . . . Character value + for more values

And then press F11 to view the keywords for the parameters:

Command example (TESTCMD) Type choices, press Enter. File . . . . . . . . . . . . . . FILE Library . . . . . . . . . . . *LIBL Server . . . . . . . . . . . . . SERVER Number . . . . . . . . . . . . . NUMBER 0 Categories . . . . . . . . . . . CATEGORY + for more values

Now I have the command I can use the GENCMDDOC to create documentation for it.

GENCMDDOC allows for documentation to be created in two forms in the IFS folder of my choosing:

• HTML file
• File containing UIM statements

I type this at any command line and press F4:

GENCMDDOC

This displays all of the parameter for this command:

Generate Command Documentation (GENCMDDOC) Type choices, press Enter. Command . . . . . . . . . . . . CMD > Library . . . . . . . . . . . > *LIBL To directory . . . . . . . . . . TODIR > '.' To stream file . . . . . . . . . TOSTMF > '*CMD ... Replace file . . . . . . . . . . REPLACE *YES

This screen is where I give the name and library the command is in, and where I want the output file to be put.

Pressing F10 shows the additional parameters, which is where I enter if I want a HTML or UIM file.

Generate Command Documentation (GENCMDDOC) Type choices, press Enter. Additional Parameters Generation options . . . . . . . + for more values

I can enter either:

• *HTML:  HTML file generated
• *UIM:  Generated file contains UIM source code

I have found that if you enter both, whatever is in the first field is generated, the other file is not. There are also additional values you can enter, but are not needed when generating help.

I first wanted to generate the help as a HTML file. To do that I used the following:

GENCMDDOC CMD(TESTCMD) TODIR('/home/MyDir') TOSTMF(testcmd.html) GENOPT(*HTML)

When I looked in the job log I could see that process that the operating system used to create the file:

Java Virtual Machine is IBM Technology for Java. PID(18399) JVM properties were loaded from a properties file. Command documentation file created for TESTCMD in MYLIB. File is /home/MyDir/testcmd.html. 1 command document(s) created successfully.

If I use the IFS tool in ACS (In the 5250 client: Actions > Integrated File System), I will find the HTML file in my folder. I right click on it, select "Download", and save it to my computer. I can then click on the saved file, on my computer, and a browser session is opened and I see the following:

To create a file in the IFS containing the UIM necessary for creating a panel group I would use the following command:

GENCMDDOC CMD(TESTCMD) TODIR('/home/MyDir') TOSTMF(testcmd.uim) GENOPT(*UIM)

After this command has completed I can look in the job log to see what happened:

Java Virtual Machine is IBM Technology for Java. PID(18404) JVM properties were loaded from a properties file. Command documentation file created for TESTCMD in MYLIB. File is /home/MyDir/testcmd.uim. 1 command document(s) created successfully.

Using the IFS tool I can see the UIM file. When I right click and select "View" I can see the UIM code, which looks like:

:pnlgrp. .************************************************************************ .* Help for command TESTCMD .************************************************************************ :help name='TESTCMD'. Command example - Help :p.The Command example (TESTCMD) command <...> .* Describe the function provided by the command. :p.:hp2.Restrictions::ehp2. :ul. :li. You must have <...> .* List all special authorities required to run the command. :li. You must have <...> .* List object or data authorities required to run the command. :li. This command is conditionally threadsafe, <...> .* If conditionally threadsafe, list threadsafe conditions or restrictions. :li. <...> .* Describe other command-level restrictions. .* Parameter-level restrictions belong in parameter help sections, not here. :eul. :ehelp.

The above is only a part of the contents of the file.

I am sure I am not the only person whose code is in source files. How do I transfer the contents of the UIM file into a source file member?

First I need to create a member in my source file. I use one for source file for all types of source, DEVSRC. To add a member to the source file I would use the Add Member command, ADDPFM:

ADDPFM FILE(DEVSRC) MBR(TESTCMDHLP)

There are various ways that the contents of a file in the IFS can be copied into a source file. For something like this I would use FTP. For detailed instructions on how to FTP files to and from the IFS you can read this post.

The steps you would need to perform are:

Start a FTP connection to the IBM i partition the file is in. In this example I am going to call my partition MYSYS, therefore, the IBM i command to start a FTP connection to MYSYS is:

FTP MYSYS

And press Enter. When FTP open I enter my user id and password.

I need to change the object name formatting from traditional IBM i (Library/File.Member) to the IFS naming method (/Directory/File).

I entered on the command line, below where it says "Enter an FTP subcommand":

namefmt 1

When that has completed I needed to "put" the contents of the file in IFS into the source file member:

put /home/MyDir/testcmd.uim /qsys.lib/mylib.lib/testsrc.file/testcmdhlp.mbr

/home/MyDir/testcmd.uim is the directory path and file name of the file in the IFS.

/qsys.lib/mylib.lib/devsrc.file/testcmdhlp.mbr Is the equivalent of:

• qsys.lib:  This is the library, QSYS, where all IBM i libraries reside
• mylib.lib:  The library MYLIB
• devsrc.file:  The (source) file DEVSRC
• testcmdhlp.mbr:  The file member TESTCMDHLP

When the FTP subcommand has completed the contents of the IFS file will have been copied in the source file member.

I prefer to use the following command to view the contents of the source file member:

STRSEU SRCFILE(*LIBL/DEVSRC) SRCMBR(TESTCMDHLP) OPTION(5)

I can now edit this file and make the help for this command more helpful.

How do I "attach" the help panel group to the command? I know of two ways. First is to use the CHGCMD to do the following:

CHGCMD CMD(TESTCMD) HLPPNLGRP(*LIBL/TESTCMDHLP) HLPID(TESTCMD)

The HLPID is the name of the help name tag, line 5 below, at the start of the TESTCMDHLP source code:

01 :pnlgrp. 02 .******************************************* 03 .* Help for command TESTCMD 04 .******************************************* 05 :help name='TESTCMD'.

I do not like this way as when someone else recreates the command by compiling the source the relationship to the help panel is lost. This is why I prefer to add the help information to the command prompt parameter at the top of the TESTCMD source member:

01 CMD PROMPT('Command example') + 02 HLPID(TESTCMD) HLPPNLGRP(TESTCMDHLP)

And then compile it.

 

You can learn more about the GENCMDDOC command from the IBM website here.

 

This article was written for IBM i 7.6, and should work for some earlier releases too.