Adding help text to CL commands

CL commands are handy, and they become even handier when you add enough help text for other people to get the most out of your utilities. So I’m thankful to Ted Holt of the increasingly misnamed Four Hundred Guru for pointing out just how straighforward a process this is.

Because I should, I have gone back to some of my earlier commands and started adding a bit of help text. DSPOSRLS is, admittely, a pretty trivial command as far as documentation goes – there are no parameters and the command can only be used interactively – but I have the source in front of me and the command does provide a conveniently simple place to start.

First, you need a source file in which to enter your help text.
crtsrcpf Library/qpnlsrc

The command I didn’t know about was this one: Generate Command Documentation (GENCMDDOC):

The Generate Command Documentation (GENCMDDOC) command generates an output file which contains documentation for a Control Language (CL) command. The generated file will be one of the following:

  • If *HTML is specified for the Generation options (GENOPT) parameter, the file will contain HyperText Markup Language (HTML) source. The generated file can be displayed using a standard internet browser, and conforms to HTML 4.0 specifications. The information used to generate the file is retrieved from the specified command (*CMD) object and any command help panel group (*PNLGRP) objects associated with the command.
  • If *UIM is specified for the GENOPT parameter, the file will contain User Interface Manager (UIM) source. The generated source is an outline for the online command help for the command. The information used to generate the file is retrieved only from the specified command (*CMD) object. This option is intended to simplify the task of writing online help for CL commands.

The command doesn’t write your documentation for you, but it does provide all the structure you need if you want your command to look like all the other ones on your system. It also makes it quite easy to see how the panel group syntax works.

And so, to the command:
GENCMDDOC CMD(Library/DSPOSRLS) TODIR('/qsys.lib/Library.lib/qpnlsrc.file') TOSTMF(dsposrls.mbr) GENOPT(*UIM)

This will create a member (DSPOSRLS) of type UIM in file QPNLSRC. Change the type to PNLGRP and then you can start editing the the generated text until you have something meaningful. The syntax struck me as being very reminiscient of Markdown which makes it quite easy to get up to speed.

Once you are hapy with your help text, you will need to create the panel group:

And now you need to rebuild the command with the help text added:

Because the panel group and command are separate objects, you do not need to recreate the command every time you change the panel group. The panel group can be changed as and when you notice the inevitable typos and the updated version will be loaded when you next press F1.

Having the help text baked into your command is handy enough as it is but there is one more rather neat trick worth mentioning. If, once you are happy with your help text, you enter the following command
GENCMDDOC CMD(DSPOSRLS) TODIR('/home/expatpaul') TOSTMF('dsposrls.html') GENOPT(*HTML)

… GENCMDDOC will spit out an IFS file, named dsposrls.html, with all the same text, but marked up for HTML. I have sent the file to my home directory but, if you use TODIR('/www/apachedft/htdocs'), the file will be created in the default location for HTML files that are served by the Apache HTTP server for i.

A better way to display ad-hoc messages

When debugging – and when developing quick and dirty utilities – I often resort to the DSPLY opcode. It isn’t pretty, but it puts information onto the screen without having to bother with DDS. There is a better way.

Display Long Text (QUILNGTX) API displays a pop-up window containing the string of text passed to it. You can even add a title to the window by passing a Message ID and (optionally) a qualified message file name.

This API has been around for a while, but it’s new to me and, after playing around with it a bit, I have now updated the DSPOSRLS utility to take advantage of it.

Pretty, isn’t it?

For the sake of completeness, I should probably add a message to a message file for this so that I can display a window title. For the sake of laziness, that’s something for the future.


Just a quick note to mention that I have updated the project pages for DSPOSRLS and DSPPGMLCK so that they now include some halfway useful compile and usage instructions. I have also committed some slightly improved README files for both of these utilities.

DSPOSRLS: Display Operating System Release

One of the surprisingly non-inuitive parts of the IBM i is that there is no easy way to identify what OS release your machine is on. Well, not if you don’t have enough authority to use DSPPTF.

A common approach is to use DSPDTAARA QSS1MRI which works, but isn’t officially supported. So this approach could stop working at any point and without notice.

The officially supported method is to use the QSZRTVPR (Retrieve Product Information) API. So I did.

DSPOSRLS is a simple command that retrieves and displays the current OS release level. I have posted the source on GitHub so feel free to browse or download it from there.