• The Four Hundred
  • Subscribe
  • Media Kit
  • Contributors
  • About Us
  • Contact
Menu
  • The Four Hundred
  • Subscribe
  • Media Kit
  • Contributors
  • About Us
  • Contact
  • Easily Create Help Text For Commands

    January 23, 2013 Ted Holt

    Extending IBM i by writing one’s own commands is empowering and gratifying, but a command without help text is like scrambled eggs without salsa. Fortunately, generating help text for a command is easy, thanks to a technique I learned from a very talented programmer named Chris Wages. Let me show you how it’s done.

    First, you must have a command, of course. Here’s the source code for command DOIT.

    CMD        PROMPT('Do it')
    
    PARM       KWD(HOW) TYPE(*CHAR) LEN(7) RSTD(*YES) +
                 DFT(*WELL) +
                 VALUES(*WELL *BETTER *BEST) +
                 EXPR(*YES) +
                 PROMPT('How should I do it?')
    
    PARM       KWD(WHEN) TYPE(*CHAR) LEN(8) RSTD(*YES) +
                 DFT(*MORNING) +
                 VALUES(*MORNING *NOON *NIGHT) +
                 MAX(3) EXPR(*YES) +
                 PROMPT('When should I do it?')
    

    I’ve created the command and tested it, and I know it works properly. Time for help text! Use the Generate Command Documentation (GENCMDDOC) command.

    GENCMDDOC CMD(MYLIB/DOIT)
              TODIR('/qsys.lib/mylib.lib/qpnlsrc.file')
              TOSTMF(doit.mbr)
              GENOPT(*UIM)
    

    Notice that the help text is placed into a source physical file called QPNLSRC. Notice also that GENCMDDOC requires the source physical file name and member name to be specified in IFS format.

    Change the source type from UIM to PNLGRP.

    At this point, I edit the source, numbering all occurrences of the substitution token, <…>. That is, I change the tokens to something like <.1.>, <.2.>, etc. This makes it easy for me to replace each token with the proper text.

    Use the Create Panel Group (CRTPNLGRP) to create the panel group object. (This is easily done with option 14 of PDM.)

    CRTPNLGRP PNLGRP(MYLIB/DOIT)
              SRCFILE(MYLIB/QPNLSRC)
              SRCMBR(DOIT)
    

    Now it’s time to connect the help text to the command. Notice the HLPPNLGRP and HLPID parameters.

    CRTCMD CMD(MYLIB/DOIT)
           PGM(*LIBL/DOIT)
           SRCFILE(MYLIB/SRC)
           SRCMBR(DOIT)
           HLPPNLGRP(DOIT)
           HLPID(*CMD)
    

    At this point, I work with two sessions. In the first one, I prompt the command to view the command text. In the other, I edit the help text source code.

    In the first session, I type the command name at a command line, press F4 to prompt, move the cursor up one line to position it in front of the first parameter, and press F1 to bring up the help text. Figure 1 below shows what I see.

    Figure 1

    Figure 1. (Click graphic to enlarge.)

    In the second session, I modify the source code as required, based on what I see in the first session. (This works especially well if you have two monitors!) I delete lines I don’t want and I change the values of substitution tokens, message IDs, etc. I prefer to make a few small mods at a time and rebuild the panel group, rather than trying to build all the help text at one time, just in case I introduce a syntax error. I especially recommend this approach to those who are not proficient with UIM.

    When I’ve finished, my help text looks like Figure 2.

    Figure 1

    Figure 2. (Click graphic to enlarge.)

    Let me point out that you do not have to recreate the command when you make a change to the panel group. Every time you press F1 for help, the system will reload the panel group. In fact, you don’t even have to exit to the command line when prompting the command. Just exit the help text, which returns you to the command prompt screen and press F1 once again.

    Commands are one of the best–and most underused and unappreciated–features of IBM i. Adding help text is an easy way to improve the usefulness of your commands.

    RELATED STORY

    Commands: Underused and Unappreciated



                         Post this story to del.icio.us
                   Post this story to Digg
        Post this story to Slashdot

    Share this:

    • Reddit
    • Facebook
    • LinkedIn
    • Twitter
    • Email

    Tags:

    Sponsored by
    Rocket Software

    Two Steps Forward, No Steps Back

    For over 35 years, Rocket Software’s solutions have empowered businesses to modernize their infrastructure, unlock data value, and drive transformation – all while ensuring modernization without disruption.

    LEARN MORE

    Share this:

    • Reddit
    • Facebook
    • LinkedIn
    • Twitter
    • Email

    Sponsored Links

    CCSS:  IBM i event monitoring: 5 great tips to help you avoid and respond to system failures
    New Generation Software:  Bring your IBM i Query, Reporting, & Analytics to the NGS-IQ Cloud
    COMMON:  Join us at the 2013 Conference & Expo, April 7 -10 in Austin, TX

    More IT Jungle Resources:

    System i PTF Guide: Weekly PTF Updates
    IBM i Events Calendar: National Conferences, Local Events, and Webinars
    Breaking News: News Hot Off The Press
    TPM @ The Reg: More News From ITJ EIC Timothy Prickett Morgan

    Mainline Buys BI Services Firm Coming Soon: Entry And Midrange Power7+ Servers

    Leave a Reply Cancel reply

Volume 13, Number 2 -- January 23, 2013
THIS ISSUE SPONSORED BY:

Help/Systems
WorksRight Software
RJS Software Systems

Table of Contents

  • Dealing With Library Lists In RSE/RDP
  • Easily Create Help Text For Commands
  • Stopping Unauthorized Users From FTPing To Your IBM i

Content archive

  • The Four Hundred
  • Four Hundred Stuff
  • Four Hundred Guru

Recent Posts

  • Liam Allan Shares What’s Coming Next With Code For IBM i
  • From Stable To Scalable: Visual LANSA 16 Powers IBM i Growth – Launching July 8
  • VS Code Will Be The Heart Of The Modern IBM i Platform
  • The AS/400: A 37-Year-Old Dog That Loves To Learn New Tricks
  • IBM i PTF Guide, Volume 27, Number 25
  • Meet The Next Gen Of IBMers Helping To Build IBM i
  • Looks Like IBM Is Building A Linux-Like PASE For IBM i After All
  • Will Independent IBM i Clouds Survive PowerVS?
  • Now, IBM Is Jacking Up Hardware Maintenance Prices
  • IBM i PTF Guide, Volume 27, Number 24

Subscribe

To get news from IT Jungle sent to your inbox every week, subscribe to our newsletter.

Pages

  • About Us
  • Contact
  • Contributors
  • Four Hundred Monitor
  • IBM i PTF Guide
  • Media Kit
  • Subscribe

Search

Copyright © 2025 IT Jungle