Problem solve Get help with specific problems with your technologies, process and projects.

Take command of your commands

User-defined commands help simplify your programs.

John Kohan

User-defined commands are one of the most under utilized objects in OS/400. The way they are defined, created and used is often misunderstood, so programmers stay away from them. Once they're mastered, however, they become a great tool to have in your toolbox.

Not only do they allow you to reduce the amount of code needed, but they also allow you to place them on a job scheduler so you don't need a user to actually enter the data. You can think of it as "pre-requesting" the report.

How easy are user-defined commands? Let's take a look at an example:

To create a report to display the current status of a customer's orders, you need a printer file, a High Level Language (HLL) program such as RPG or Cobol, and you need to ask the user for the customer's number. If you create a screen and a CL program to invoke the report, the process can run only in an interactive mode using a traditional interface such as CA400. The display file would contain about 10 lines of source, and the CL program would contain about the same.

But if you create a user-defined function, the screen and program would contain three lines of source code total. The screen would also look like a traditional iSeries command and would be used as such. The process could be called interactively, placed on the job scheduler or called from a Web interface such as

Below is a simple command:

CMD        PROMPT('Customer Status Report')

PARM       KWD(CUST) TYPE(*DEC) LEN(4)  + 
                  MIN(1) PROMPT('Customer Number') 
                  MIN(1)   PROMPT('Status')                     

When you compile your command (CRTCMD), set the "PGM" parameter to the name of the HLL program you want to receive the user's request. When the user presses enter, the program you entered on the PGM parameter will get called and passed these values.

Commands may be as simple or as complex as we need them. They can have default parameters so the user does not need to remember them. They can have special values that convert the parameters from one the user would understand to one the program can use. They can have qualified parameters so if the user selects a value that requires more information, the command will automatically ask for it.

Commands may also validate values so you can make sure the user inputs values you control. They may also have multiple values for the same field so the user may ask for many selections at once.

User-defined commands may seem complex, but their total lines of source code is usually fewer than 10. So even a complex command will require less coding than one simple screen, and it will increase functionality and flexibility many times over.

There are six statements (or OPCODE for RPG programmers) in command definition:
CMD (command)
DEP (dependent)
ELEM (element)
PARM (Parameter)
PMTCTL (Prompt Control)
QUAL (Qualifier) statement

You only need to use the "CMD" statement and the "PARM" statement to create your own commands.

Visit the iSeries information center to review the command syntax.

About the author: John Kohan is a senior programmer analyst at CT Codeworks.


  • User-defined commands to the rescue member Eitan Rosenberg shows you a technique for submitting a report using a homegrown command.
  • User-defined options make it easier to work with source objects
    If you're like progbrammer Richard Cranston, you often work within pdm working with source members. Richard added two 'User Defined Options' that call his utility programs, which will issue "CHGOBJOWN" or "EDTOBJAUT" commands on the source objects. The "CHGOBJOWN" program will prompt the command automatically so the new owner information can be entered.
  • Use FNDMSG command to maintain and manage error messages
    Using external message files is a great way to keep your error messages external to your program visible and easy to maintain. But this file can get out of control if messages are continually added. You can end up with duplicate or similar error messages. And if you're trying to maintain any consistency with your error messages, you'll have a problem. To solve that problem, site expert Tim Granatir created the FNDMSG command.

Dig Deeper on iSeries CL programming