It's easy with the GENCMDDOC command!
This article is the sixth in a series related to creating user commands. The first five articles introduced how to define various command parameter features and then implement those features within the command's command processing program (CPP). In this article, we will look at one way to provide online help for user-created commands. The approach we will review utilizes the Generate Command Documentation (GENCMDDOC) command, which is provided starting with V5R3 of the i operating system. The GENCMDDOC command is documented here and, as one of its options, can generate an output file containing an outline to be used for documenting a CL command.
Before generating this outline, though, let's make a minor change to the TRMLFTCHR command definition. This change, though small, can improve our productivity down the road as you will see shortly. Currently, the TRMLFTCHR command is defined as shown below.
Cmd Prompt('Trim Left Characters')
Parm Kwd(Var) Type(*Char) Len(1) RtnVal(*Yes) +
Min(1) Vary(*Yes *Int4) +
Prompt('Decimal value')
Parm Kwd(TrmChr) Type(*Char) Len(1) Dft(0) +
SpcVal((0)) Max(50) +
Prompt('Character to trim')
Parm Kwd(AllTrmChr) Type(*Char) Len(1) +
Dft(*TrmChr) SpcVal((*TRMCHR X'FF')) +
Prompt('Character for all trimmed')
This definition has served us well so far, but having the prompt text for the command (and for all of the parameters of the command) coded as literals in the command definition is not necessarily the best way to go. If we were to ever decide to change some of this text (have you noticed, for instance, that the prompt text for the VAR keyword is still "Decimal value" even though the command has supported any character values since the fourth article of this series, "Cut, Snip, Trim with TRMLFTCHR"?), we would need to actually change the command source (and, having edited the command source, risk inadvertently changing more than just the prompt text). A better approach would be to use message descriptions for the prompt text. By using message descriptions, we could change the prompt text (including being able to provide translations to other languages if our company decided to go international) without needing to maintain the command definition (though on releases prior to V6R1, you would still need to recompile the command; you just wouldn't need to change the source).
Changing the TRMLFTCHR command to use message descriptions for prompting is quite easy to do. The following commands create a message file named USERMSGF in library VINING and then add message descriptions to the message file for the TRMLFTCHR command and each parameter of the command. Note that you should change VINING to whatever library name is appropriate for you.
CRTMSGF MSGF(VINING/USERMSGF)
ADDMSGD MSGID(TRM0001) MSGF(VINING/USERMSGF) MSG('Trim Left Characters')
ADDMSGD MSGID(TRM0002) MSGF(VINING/USERMSGF) MSG('Value')
ADDMSGD MSGID(TRM0003) MSGF(VINING/USERMSGF) MSG('Character to trim')
ADDMSGD MSGID(TRM0004) MSGF(VINING/USERMSGF) MSG('Character for all trimmed')
Do You Support Multiple Language Environments?
If all of your users run with the same language environment (national language, keyboard definitions, CCSID, etc.) as your developers do, then you can skip to the heading "Updating TRMLFTCHR". If you do support multiple language environments, then ensure that your job CCSID is not 65535 prior to adding the message descriptions shown above. If the Display Job command DSPJOB OPTION(*DFNA) shows that your current job has a Coded Character Set Identifier (CCSID) value of 65535, then use the Change Job command CHGJOB CCSID(XXX), replacing XXX with an appropriate CCSID value. You will discover the benefit of this change in a following article.
Updating TRMLFTCHR
With these messages in place, we can now make the following updates to the TRMLFTCHR command definition.
Cmd Prompt(TRM0001)
Parm Kwd(Var) Type(*Char) Len(1) RtnVal(*Yes) +
Min(1) Vary(*Yes *Int4) Prompt(TRM0002)
Parm Kwd(TrmChr) Type(*Char) Len(1) Dft(0) +
SpcVal((0)) Max(50) Prompt(TRM0003)
Parm Kwd(AllTrmChr) Type(*Char) Len(1) +
Dft(*TrmChr) SpcVal((*TRMCHR X'FF')) +
Prompt(TRM0004)
And we can recreate the TRMLFTCHR command using the command below (after ensuring that library VINING—or the library that you used for message file USERMSGF—is in your library list).
CRTCMD CMD(TRMLFTCHR) PGM(TRMLFTCHR) ALLOW(*IPGM *BPGM *IMOD *BMOD)
PMTFILE(USERMSGF)
Note that, if your system is at V6R1 or later, then you can also decide, rather than just PMTFILE(USERMSGF), to specify PMTFILE(USERMSGF *DYNAMIC) on the CRTCMD command or PMTFILE(USERMSGF *DYNAMIC) on the CMD statement of the TRMLFTCHR command definition. The specification of *DYNAMIC enables the command to dynamically retrieve the prompt text when the command is prompted, removing the need to recreate the command whenever a CMD or PARM PROMPT referenced message description is changed. With releases prior to V6R1, or if the default value of *STATIC is used with V6R1 and later releases, the message text is only brought into the command object at compile time, which is why recreation of the command is necessary if you want to change the prompt text. But the key point is that either of these approaches avoids the need to recompile the TRMLFTCHR CPP.
With the prompt text now defined through message descriptions, let's generate an outline of the command documentation for TRMLFTCHR using the GENCMDDOC command. As mentioned earlier, the GENCMDDOC command can generate an output file that contains an outline to be used as a starting point for documenting a CL command. This outline will be in a source language known as User Interface Manager (UIM) and will include information related to the command and its parameters, which is retrieved from the TRMLFTCHR command object itself. As the command definition doesn't include any information on how the parameters work (only how the parameters are defined), we will want to add descriptive text to this generated outline and then create a Panel Group (object type *PNLGRP) from the UIM source statements. A panel group is an object that, among other things, can contain online help information that is shown when prompting a CL command. The GENCMDDOC generated source is stored in a stream file (*STMF) that, among other types of files, can be a source file member. As the Create Panel Group (CRTPNLGRP) command supports only source physical files, and the default source file name is QPNLSRC, we will store our generated source in a source file named QPNLSRC. Assuming we want the source to be stored in library VINING, use the following command to create the QPNLSRC source file.
CRTSRCPF FILE(VINING/QPNLSRC)
To now generate the command documentation outline as member TRMLFTCHR of VINING/QPNLSRC, you can use the following command (again replacing VINING in the TODIR parameter to the appropriate library name).
GENCMDDOC CMD(TRMLFTCHR) TODIR('/QSYS.LIB/VINING.LIB/QPNLSRC.FILE')
GENOPT(*UIM)
Opening the source member TRMLFTCHR in source file QPNLSRC using whatever editor you typically use when viewing or changing CL source, the first few lines of the source should look similar to the following:
:pnlgrp submsgf='VINING/USERMSGF'.
.**********************************************************************
.* Help for command TRMLFTCHR
.**********************************************************************
:help name='TRMLFTCHR'.
&msg(TRM0001). - Help
:p.The &msg(TRM0001). (TRMLFTCHR) command <...>
.* Describe the function provided by the command.
:p.:hp2.Restrictions::ehp2.
What you are seeing is the generated UIM source. In the next article, we'll look at and update this source, but I do want to point out one item today. The sixth and seventh lines of the source should be similar to the following:
&msg(TRM0001). - Help
:p.The &msg(TRM0001). (TRMLFTCHR) command <...>
UIM supports the use of text replacement with a feature known as symbols. Symbols start with an ampersand (&), which is followed by a symbol name such as msg, and then, depending on the symbol name, additional information such as a message ID, and finally a period (.) to end the symbol. One very handy symbol is the &msg symbol. The symbol "&msg(TRM0001)." will cause the panel group compiler to extract the first-level message text of message description TRM0001 and then substitute this text in place of the symbol (everything from the initial ampersand to the closing period). That is, the help text for the sixth source line will actually display as "Trim Left Characters – Help" when displayed by a user prompting the TRMLFTCHR command. If a year from now we decide to change the textual name of the command or any of the parameter prompts, we can simply change the message text for the appropriate message and recreate the panel group. The help text will then reflect the latest and greatest command prompt text anywhere that we used the &msg symbol within the panel group, with no additional work on our part.
Contrast this with the GENCMDDOC output if we didn't use message descriptions for the prompt text. In that case, the first few lines of generated source would be this:
:pnlgrp.
.**********************************************************************
.* Help for command TRMLFTCHR
.**********************************************************************
:help name='TRMLFTCHR'.
Trim Left Characters - Help
:p.The Trim Left Characters (TRMLFTCHR) command <...>
.* Describe the function provided by the command.
:p.:hp2.Restrictions::ehp2.
In this case, the literal text from the command definition is brought in. Needing to change the prompt text in this situation will involve searching for each occurrence of the prompt text and then changing it (and hopefully changing it correctly in all cases as this is one very tedious task). Using literal prompt values in the command definition is clearly not a good use of a developer's time when message descriptions allow for such easy reuse of the prompt text—unless of course the command being created is just a "one time and then throw it away" solution. But I suspect we all know how often that "one time" fix is still in use five years later!
In the next article, we'll look at some of the details of the UIM as it relates to providing online help text for CL commands. In the meantime, if you just can't wait to dig into the UIM, you can find much of the UIM reference material in Appendix A: UIM Panel Group Definition Language, of the Application Display Programming manual, which is located here.
More CL Questions?
Wondering how to accomplish a function in CL? Send your CL-related questions to me at
Bruce Vining is president and co-founder of Bruce Vining Services, LLC, a firm providing contract programming and consulting services to the System i community. He began his career in 1979 as an IBM Systems Engineer in St. Louis, Missouri, and then transferred to Rochester, Minnesota, in 1985, where he continues to reside. From 1992 until leaving IBM in 2007, Bruce was a member of the System Design Control Group responsible for OS/400 and i5/OS areas such as System APIs, Globalization, and Software Serviceability. He is also the designer of Control Language for Files (CLF).A frequent speaker and writer, Bruce can be reached at
MC Press books written by Bruce Vining available now on the MC Press Bookstore.
 |
||
 |
|
IBM System i APIs at Work Leverage the power of APIs with this definitive resource. List Price $89.95 Now On Sale
|
More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.
TRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now! Request Now.
Forms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.
Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:
Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.
IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn:
LATEST COMMENTS
MC Press Online