Take command of the AS/400.

by Ernie Malaga

It doesn't take long to realize that OS/400 has hundreds of commands. That much can be seen by browsing through the CL Reference Guide. It doesn't take long to realize, either, that the operation of the entire system is performed by executing commands; most of these commands can be included in a CL program for serial processing.

Let's imagine for a moment that OS/400 didn't use commands. Depending upon what you want to do, you must CALL different programs. For example, there might be a program called QGENRPG to run the RPG compiler. Because QGENRPG is a program, you must pass the parameters in a certain order which you must either memorize or dig up in the reference manuals. Pretty cumbersome, actually. Picture having to type CALL QGENRPG (PRODLIB/PGMA PRODLIB/QRPGSRC) instead of CRTRPGPGM PGM (PRODLIB/PGMA) SRCFILE (PRODLIB/ QRPGSRC). In the first case, you must remember the correct order of the parameters, and there are no keywords like PGM( ) and SRCFILE( ) to clue you into the correct syntax. Although the second method requires more typing, it is more readily understood. Besides, the parameters have keywords, so you can enter them in any order.

In addition to this, commands offer the command prompter, a powerful feature that creates prompt displays for you. These displays automatically include the basic function keys (F3, F12 and so on) at the bottom of the screen. If you have ever worked on a System/36, you may remember having to create prompt display formats using SDA whenever you created a new procedure to be run interactively. OS/400 doesn't require you to do so; this is automatically taken care of using a standard format, no matter what command is created. This brings another benefit: consistency in the user interface.

Getting Started

To get started writing commands, you'll need to have the QCMDSRC source physical file in the library of your choice. For the rest of this article I will use the name MYLIB for the library; you can replace it with the name of one of your libraries. To create this file, use the CRTSRCPF command:

 CRTSRCPF FILE(MYLIB/QCMDSRC) + TEXT('Command source') 

Okay, let's create a simple command with no parameters, such as Display Current User (DSPCURUSR). This command will display an information message with the current user's profile name. First of all, the command must be entered with SEU into QCMDSRC:

 STRSEU SRCFILE(MYLIB/QCMDSRC) + SRCMBR(DSPCURUSR) TYPE(CMD) ) 

Because this command has no parameters, we need only to enter one statement for this command, as you can see in 1a. This makes up the CDO (Command Definition Object). But then we also need a small program that will actually perform the task; this program is listed in 1b. All that program does is retrieve the user profile name of the current user and send it as a completion message to the requesting workstation. For the record, this program is usually referred to as the CPP (Command Processing Program). After keying in both source members, create the command with the CRTCMD (Create Command) command:

Because this command has no parameters, we need only to enter one statement for this command, as you can see in Figure 1a. This makes up the CDO (Command Definition Object). But then we also need a small program that will actually perform the task; this program is listed in Figure 1b. All that program does is retrieve the user profile name of the current user and send it as a completion message to the requesting workstation. For the record, this program is usually referred to as the CPP (Command Processing Program). After keying in both source members, create the command with the CRTCMD (Create Command) command:

 CRTCMD CMD(MYLIB/DSPCURUSR) + PGM(MYLIB/CUR001CL) + SRCFILE(MYLIB/QCMDSRC) Next, create the CL program: CRTCLPGM PGM(MYLIB/CUR001CL) + SRCFILE(MYLIB/QCLSRC) 

It is the execution of the CRTCMD command which "ties" the CDO and the CPP together. To execute the new DSPCURUSR command, simply type DSPCURUSR and press Enter. If you get a message saying that the command can't be found in the library list, simply add MYLIB to your library list, like this:

 ADDLIBLE LIB(MYLIB) 

Passing Parameters

Of course commands such as DSPCURUSR are not common; most commands have parameters in order to add flexibility. For example, let's see how we could write a command to display either the date or the time of day, or both, again as a message to the requesting workstation. We will call this command Display Date and/or Time (DSPDATTIM). The CDO is listed in 2a, and the CPP is listed in 2b. After you enter them, create the command and the CL program:

Of course commands such as DSPCURUSR are not common; most commands have parameters in order to add flexibility. For example, let's see how we could write a command to display either the date or the time of day, or both, again as a message to the requesting workstation. We will call this command Display Date and/or Time (DSPDATTIM). The CDO is listed in Figure 2a, and the CPP is listed in Figure 2b. After you enter them, create the command and the CL program:

 CRTCMD CMD(MYLIB/DSPDATTIM) + PGM(MYLIB/DAT001CL) + SRCFILE(MYLIB/QCMDSRC) CRTCLPGM PGM(MYLIB/DAT001CL) + SRCFILE(MYLIB/QCLSRC) 

Let's take a minute to analyze the CDO. As you can see, there are two PARM statements after the CMD statement. Each PARM statement describes one parameter and one only. As you can see, they are identical except in their KWD (keyword) and PROMPT (prompt).

KWD (keyword) is the parameter keyword that goes outside the parenthesis when you execute the command or include it in a CL program. It is actually the name of the parameter. TYPE and LEN describe the type of value that the parameter will hold, and how long it can be; these keywords are just like those in a CL program, except that in the CDO, there are many more data types than in CL.

DFT(*YES) indicates that the parameter will default to the value *YES. RSTD(*YES) and VALUES(*YES *NO) specify that the parameters will have restricted values, and that there are only two values acceptable, *YES and *NO. Remember that the value *YES has been defined as the default.

When you type DSPDATTIM and press the F4=Prompt key, the command prompter will create an entry panel for you to complete. Because we indicated PROMPT text for each parameter, that text will appear to the left of the input field. Also, the input field itself will already contain the default value *YES. To the right of the input field, the command prompter will list the acceptable values.

Pressing Enter executes the command. Because the command was created with DAT001CL as the associated CPP, this program receives the parameters from the CDO, one-to-one. For this reason the parameters must match in number, type, and length between the CDO and the CPP. As you can see, like the CDO, the CPP accepts two parameters. And like the CDO, both parameters are TYPE(*CHAR) LEN(4).

That means that in the CL program, the variable &DATE will have either *YES or *NO, and the same thing will happen with variable &TIME. Please notice that because the command has been coded so that only *YES and *NO are acceptable values, the CL program doesn't have to check that for accuracy; the CL program can take for granted that both will have acceptable values. Now program DAT001CL goes about its business of retrieving the system date and/or system time from the system values and creating the &MSGDTA string, which is what is actually sent as a message. Plain and simple.

The command could have been executed without the prompter, of course. Simply type in DSPDATTIM DSPDAT(*YES) DSPTIM(*YES) and press Enter. Notice how the keywords come into play. Also notice that the keyword (name of the parameter) doesn't have to match the name of the variable that receives it in the CPP: the first parameter, for example, is called DSPDAT in the CDO but is called &DATE in the CPP.

Because we defined the parameters as having value *YES by default, both the system date and time will be displayed if you type in DSPDATTIM and press Enter (without parameter values). Finally, the parameters can be entered positionally, without keywords, if so desired: DSPDATTIM *YES *YES.

Adding Variety to the CPP

The CPP can be any type of program, provided that the parameters being received from the CDO are supported in the language being used, and that an interactive program isn't used in a command that is run in batch mode. For example, CL doesn't support binary variables but the CDO does. So, if you create a command that passes binary data, you'll have to write the CPP in another language, which is perfectly alright.

You should use the language that best suits the job to be performed by the command. If you write a command that must update database files, for example, you should consider writing the CPP in RPG or another HLL. Obviously, CL is not the way to do this.

Two New Topics: Qualified Names and Error Messages

You are probably aware that OS/400 references objects by way of a qualified name, meaning that the name of the object is qualified with the name of the library where it resides. Let's suppose you want to create a command to display the first member of a database file. Never mind that the DSPPFM command is already available - we will create our own command just for the fun of it. Let's call it DSPFPFM (Display First Physical File Member). In order to tell the system which file to display, however, we must mention the name of the file and the library where it resides.

Now, you could create the DSPFPFM command using two separate parameters: one for the file and the other for the library. This approach will work, but IBM has devised another method whereby an entire qualified name can be passed in a single parameter. It involves a little more work, but it will make your commands more professional-looking. Let's see how it's done. 3a shows the CDO and 3b the CPP. Notice in 3a that the FILE parameter has been declared as having TYPE(Q1); Q1 is actually a label pointing to the two QUAL statements that further define the parts of the qualified name. When the command is executed, both parts of the qualified name are passed to the CL program in a single parameter. Suppose that you executed the command by typing the following:

Now, you could create the DSPFPFM command using two separate parameters: one for the file and the other for the library. This approach will work, but IBM has devised another method whereby an entire qualified name can be passed in a single parameter. It involves a little more work, but it will make your commands more professional-looking. Let's see how it's done. Figure 3a shows the CDO and Figure 3b the CPP. Notice in Figure 3a that the FILE parameter has been declared as having TYPE(Q1); Q1 is actually a label pointing to the two QUAL statements that further define the parts of the qualified name. When the command is executed, both parts of the qualified name are passed to the CL program in a single parameter. Suppose that you executed the command by typing the following:

 DSPFPFM FILE(MYLIB/MYFILE) 

The CL program receives this information in variable &QUALF, in the following

format:

 'MYFILE MYLIB ' 

that is, two 10-character strings put together, with the file name first and the library name second. Why are the components backwards? After all, we typed them in with the library first, a slash, and the file name second. Yet the program receives them the other way around. To answer this question one must remember that OS/400 comes from CPF, the S/38 operating system. On that system, the syntax was reversed and the separator character was not a slash, but a dot. Apparently, IBM copied most of CPF "as is" for simplicity. Reversing the components of the qualified name was a compromise good enough, and they avoided a major rewrite.

The CPP first breaks the qualified name into its two components with the %SST (substring) function, then it checks the existence of the library and the file using the CHKOBJ command. If both checks pass, then the standard DSPPFM command is executed with MBR(*FIRST) so that the first member of the database file is displayed.

I will explain the second topic, sending error messages, through figures 3a and 3b. Notice that the CPP uses the CHKOBJ command to verify the existence of the library and the file. If either doesn't exist, the CHGVAR command is used to set variable &MSGDTA to a certain error message text, and then control is passed by way of a GOTO command to tag ERROR. At this point two SNDPGMMSG (Send Program Message) commands are executed. The first one sends a *DIAG (diagnostic) message using the text we placed in &MSGDTA. Message CPF9898 will copy whatever you put in the MSGDTA parameter plus a period. The second SNDPGMMSG sends an *ESCAPE message CPF0002. Together these two messages will alert the user (whether a person or another program) that there has been a problem with the DSPFPFM command just requested.

Defining Lists in Parameters

Just as a qualified name can be considered a list of two elements (although in reality it is not a list), OS/400 supports lists of any given length in commands. Lists can be divided into three types. Simple lists contain elements of the same type and length, and the order of the elements doesn't necessarily matter. For example, the CHGLIBL (Change Library List) command accepts a couple dozen values in the LIBL parameter. Let's see an actual example:

 CHGLIBL LIBL(MYLIB PRLIB + TESTLIB UTILITY PRODLIB) 

In this example, the LIBL parameter holds five library names. Since each library name can have 10 characters, it is obvious that the CPP would receive the list of libraries in a 50-byte variable, right? Wrong. The CPP will receive the list of libraries in a 52-byte variable. The two extra bytes will contain the number of elements in the list, coded in binary, and will precede the list of values.

Simple lists are easy to code in the CDO. The PARM (parameter) statement must simply have a maximum number of elements code, such as MAX(5) for five elements. The list will then accept any number of elements up to five. If you also code the minimum, like MIN(2), then the list must have at least two elements.

Mixed lists contain elements of different types or lengths, and therefore the elements must be entered in a specific order. For example, the CHGJOBD (Change Job Description) command has a parameter called LOG which describes what to write into the job log. The LOG parameter is a mixed list with three elements: a level number from 0 to 4, a severity code from 0 to 99, and a text description which can have the values *MSG, *SECLVL, or *NOLIST. So it is possible to execute the CHGJOBD command like this:

 CHGJOBD JOBD(QDFTJOBD) + LOG(4 0 *NOLIST) 

Mixed lists are a bit more complicated to code; they require the ELEM statements to be coded for each parameter that is to be considered a mixed list. Let's create a command to change a job description's logging values. We'll call it CHGJOBDLOG. The CDO is listed in 4a, and the CPP is listed in 4b.

Mixed lists are a bit more complicated to code; they require the ELEM statements to be coded for each parameter that is to be considered a mixed list. Let's create a command to change a job description's logging values. We'll call it CHGJOBDLOG. The CDO is listed in Figure 4a, and the CPP is listed in Figure 4b.

Let's see, then, what happens when you execute the command like this:

 CHGJOBDLOG JOBD(MYJOBD) + LOG(3 70 *SECLVL) 

The first parameter presents no problems - it is a simple value, not even a qualified name, although it should have been one to include the name of the library where the job description is found. As it is now, the library list will always be used.

The second parameter is tricky. If you add up the lengths of the three elements, you obtain 10. Why is the CPP receiving this list into an 18-byte variable? In other words, what are the other eight bytes? Like a simple list, the mixed list contains a two-byte header which has the number of elements coded in binary. In a mixed list, after this header, there is another two-byte binary code for each element in the list, showing the location of the first byte of each element's data, or its "displacement." Because there are three elements in the list, there will be six bytes in binary, plus the two bytes that every list begins with, making eight. So the actual data of the list begins on the ninth byte. This is why the %SST (substring) functions coded in the CPP begin work on byte number 9. The first eight bytes are garbage to us, but they must be accounted for.

Lists within lists are even more complex. Basically speaking, they're simple lists where each element is a mixed list. Got the idea? If you imagine a list as a paper bag, then the list within list is a paper bag containing several smaller bags inside. And before you ask, you cannot nest lists within lists to further levels; two levels is the maximum. Rather than trying to explain how lists within lists are organized, I'd like to refer you to the CL Programmer's Guide, page 9-21, where you'll find a rather good explanation. As a matter of fact, the whole of Chapter 9 is dedicated to the topic of creating commands.

Naming Conventions

IBM did an marvelous job when they came up with the set of commands for CPF on the S/38. This set of commands has been used again on the AS/400, with some modifications as were deemed necessary. You may want to use IBM's command naming conventions in order to keep all commands - yours and IBM's - as consistent as possible.

IBM's naming system has been described before in Midrange Computing, so I won't repeat it here. All the abbreviations used in IBM commands are listed in Appendix F of the CL Reference Guide, Volume 1.

Are Commands Really Necessary?

After reading this article you may have realized the power of commands, and hopefully you'll be eager to create some of your own. On the other hand, you may be thinking along these terms: "Why go through so much work, when my users are accustomed to taking menu options?" This is a valid point. However, you should be aware of the fact that, by forcing your users to take menu options, you're also forcing them to go through the menus in order to reach the very specific task they need to perform. This may involve paging through several (or many) menus.

If commands were used, on the other hand, the user would have the choice of using the menus that he or she is used to, or taking the shortcut of running the command. Imagine for a minute that OS/400 didn't have commands, and everything had to be done through menus, even system operator-type activities. Wouldn't you say that this would be cumbersome, especially for an experienced system operator? The same concept applies to regular users.

Consider, too, the user interface. If you opt for using programs throughout your system, you will have to design panels for interactive tasks, even for requesting things such as reports. That's more work, and no two programmers will come up with panels that look identical. In contrast, when you create commands, the system takes away from you the chore of having to create the panel, and all such panels will look similar. When your users learn how to use one of them, they'll have learned how to use them all.

Conclusion

You can create very flexible commands that can be adapted to almost any activity. They can have meaningful names that will make them easy to remember, and have a consistent user interface provided by the command prompter. And you can include your own commands in CL programs, or execute them from HLL programs with QCMDEXC.

To be sure, this article hasn't covered all there is to say about creating commands. Chapter 9 of the CL Programmer's Guide is an excellent tour on the subject. Chapter 4 of the CL Reference Guide, Volume 1, is also worth reading, although it is meant to be used as reference text, so it can be confusing for the uninitiated.

Try commands. You will learn to love them.

Creating Commands

Figure 1A DSPCURUSR command

 DSPCURUSR: CMD PROMPT('prompt(''Display Current User'')') 
 
 Creating Commands
 
 Figure 1B CL program CUR001CL
 
 CUR001CL: + PGM DCL VAR(&USRPRF) TYPE(*CHAR) LEN(10) RTVUSRPRF RTNUSRPRF(&USRPRF) SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA(&USRPRF) + MSGTYPE(*COMP) ENDPGM 
 
 Creating Commands
 
 Figure 2A DSPDATTIM command
 
 DSPDATTIM: CMD PROMPT('Display Date and Time') PARM KWD(DSPDAT) TYPE(*CHAR) LEN(4) RSTD(*YES) + DFT(*YES) VALUES(*YES *NO) PROMPT('Display- system date') PARM KWD(DSPTIM) TYPE(*CHAR) LEN(4) RSTD(*YES) + DFT(*YES) VALUES(*YES *NO) PROMPT('Display- system time') 
 
 Creating Commands
 
 Figure 2B CL program DAT001CL
 
 DAT001CL: + PGM PARM(&DATE &TIME) DCL VAR(&DATE) TYPE(*CHAR) LEN(4) DCL VAR(&TIME) TYPE(*CHAR) LEN(4) DCL VAR(&SYSDAT) TYPE(*CHAR) LEN(6) DCL VAR(&SYSTIM) TYPE(*CHAR) LEN(6) DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(20) IF COND(&DATE *EQ '*YES') THEN(DO) RTVSYSVAL SYSVAL(QDATE) RTNVAR(&SYSDAT) CHGVAR VAR(&MSGDTA) VALUE(&SYSDAT) ENDDO IF COND(&TIME *EQ '*YES') THEN(DO) RTVSYSVAL SYSVAL(QTIME) RTNVAR(&SYSTIM) CHGVAR VAR(&MSGDTA) VALUE(&MSGDTA *BCAT &SYSTIM) ENDDO SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA(&MSGDTA) + MSGTYPE(*COMP) ENDPGM 
 
 Creating Commands
 
 Figure 3A DSPFPFM command
 
 DSPFPFM: CMD PROMPT('Display First File Member') PARM KWD(FILE) TYPE(Q1) MIN(1) PROMPT('Name of the + file') Q1: QUAL TYPE(*NAME) LEN(10) MIN(1) QUAL TYPE(*NAME) LEN(10) MIN(1) PROMPT('Library') 
 
 Creating Commands
 
 Figure 3B CL program FPFM001CL
 
 FPFM001CL: + PGM PARM(&QUALF) DCL VAR(&QUALF) TYPE(*CHAR) LEN(20) DCL VAR(&FILE) TYPE(*CHAR) LEN(10) DCL VAR(&LIB) TYPE(*CHAR) LEN(10) DCL VAR(&MSGDTA) TYPE(*CHAR) LEN(10) CHGVAR VAR(&FILE) VALUE(%SST(&QUALF 1 10)) CHGVAR VAR(&LIB) VALUE(%SST(&QUALF 11 10)) CHKOBJ OBJ(&LIB) OBJTYPE(*LIB) MONMSG MSGID(CPF9801) EXEC(DO) CHGVAR VAR(&MSGDTA) VALUE('Library not found') GOTO CMDLBL(ERROR) ENDDO CHKOBJ OBJ(&LIB/&FILE) OBJTYPE(*FILE) MONMSG MSGID(CPF9801) EXEC(DO) CHGVAR VAR(&MSGDTA) VALUE('File not found') GOTO CMDLBL(ERROR) ENDDO DSPPFM FILE(&LIB/&FILE) GOTO CMDLBL(ENDPGM) ERROR: + SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA(&MSGDTA) + MSGTYPE(*DIAG) SNDPGMMSG MSGID(CPF0002) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) ENDPGM: + ENDPGM 
 
 Creating Commands
 
 Figure 4A CHGJOBDLOG command
 
 CHGJOBDLOG: CMD PROMPT('Change Job Description Logging') PARM KWD(JOBD) TYPE(*SNAME) LEN(10) MIN(1) + PROMPT('Job description name') PARM KWD(LOG) TYPE(L1) PROMPT('Job logging') L1: ELEM TYPE(*CHAR) LEN(1) DFT('4') RANGE('0' '4') + PROMPT(LEVEL) ELEM TYPE(*CHAR) LEN(2) DFT('00') RANGE('00' '99') + PROMPT(SEVERITY) ELEM TYPE(*CHAR) LEN(7) RSTD(*YES) DFT(*NOLIST) + VALUES(*MSG *SECLVL *NOLIST) PROMPT(Text) 
 
 Creating Commands
 
 Figure 4B CL program JOB001CL
 
 JOB001CL: + PGM PARM(&JOBD &LOGLIST) DCL VAR(&JOBD) TYPE(*CHAR) LEN(10) DCL VAR(&LOGLIST) TYPE(*CHAR) LEN(12) DCL VAR(&LEVEL) TYPE(*CHAR) LEN(1) DCL VAR(&SEVERITY) TYPE(*CHAR) LEN(2) DCL VAR(&TEXT) TYPE(*CHAR) LEN(7) CHKOBJ OBJ(&JOBD) OBJTYPE(*JOBD) MONMSG MSGID(CPF9801) EXEC(DO) SNDPGMMSG MSGID(CPF9898) MSGF(QCPFMSG) MSGDTA('Job + description not found') MSGTYPE(*DIAG) SNDPGMMSG MSGID(CPF0002) MSGF(QCPFMSG) MSGTYPE(*ESCAPE) GOTO CMDLBL(ENDPGM) ENDDO CHGVAR VAR(&LEVEL) VALUE(%SST(&LOGLIST 3 1)) CHGVAR VAR(&SEVERITY) VALUE(%SST(&LOGLIST 4 2)) CHGVAR VAR(&TEXT) VALUE(%SST(&LOGLIST 6 7)) CHGJOBD JOBD(&JOBD) LOG(&LEVEL &SEVERITY &TEXT) ENDPGM: + ENDPGM