Midrange Programmer

If you're an iSeries programmer or operator, you probably employ OS/400 commands on a daily basis. Commands make it easy to get things done on the iSeries. But have you ever wanted something more from an OS/400 command? Better yet, have you ever wished for a command that doesn't exist on the '400? If you answered yes to either question, you've come to the right place, because this article will explain the basic steps for creating your own OS/400 commands.

To write your own CL commands, there are four steps you have to take. Three of these steps are required, and the fourth is optional. Creating an OS/400 command can be very easy or very complex and complicated, requiring a lot of coding and testing before they are implemented. The example in this article will be closer to the easy side, but it will include the optional step and will be primed for extension. It's up to you to drink the water once I've led you to it.

The first step is the command source. This is the code that you will enter and compile to run the actual command. This source will contain no business or command processing logic; it will, however, contain the source necessary to allow a user to enter the parameters that will eventually guide the command processing logic. Before we take a look at the example, I want to provide a brief introduction to how to enter command source statements and what those command source statements are.

You enter command source statements as you would any other type of language. You will probably have a source file named QCMDSRC, but, as you may know, the name of the source file doesn't really matter. The source type of your command source is going to be CMD, just as RPG source is either RPG or RPGLE, and CL source is CLP. And, as with RPG and CL, or any other high-level language, there are specific syntax rules to follow. Commands are no exceptions. The good news is that there aren't that many rules to follow. The bad news is that some of the syntax rules can be complicated. The following is a list of keywords and a description of each:

CMD--The command statement is used to determine the prompt text for the command being created; that is, the text that is shown at the top center of the display when the user types the command name and presses F4 to prompt. There can be one, and only one, CMD statement per command, and it can be placed anywhere within the source. The usual practice is to make it the first statement of the command source.

DEP--The dependent statement is used to define the relationship between parameters and parameter values that have to be checked when the command is run. You can define the DEP statement to always check the relationship, to only check when a specific keyword is specified, or to check a keyword value using a logical expression to determine dependency.

ELEM--The element statement is used to provide the user with the option of entering more than one value for a parameter. You may have seen this before in some of the IBM-supplied commands. Usually the extra space to enter multiple values for a single parameter is obtained by entering a plus (+) sign as a value and pressing the Enter key. Take a look at the display object description (DSPOBJD) command. You will see that the Object Type parameter allows you to enter multiple values. This is an example of the ELEM statement at work.

PARM--The parameter statement is used to allow the user to enter values on the command screen. It is the basic building block used when writing commands. Parameters will appear on the screen in the order in which they are coded, so you must take that into consideration. You can have a maximum of 75 parameters per command. I don't know of many that push that limit, but the CPYF command comes to mind as one that might.

PMTCTL--The parameter control statement is used to control whether a parameter is prompted. You refer to a parameter control label inside a PARM statement. Then, at the label defined in the PARM statement, you code a condition that has to be met before the original parameter is prompted. The most common use of this statement can be seen in the DSPOBJD command. When you prompt that command, you are shown four parameters initially. If you enter *OUTFILE as a value in the last parameter, and Output, and press the Enter key, you will be presented with three additional parameters. This is an example of the PMTCLT statement in action. It is only prompted when the Output parameter is equal to *OUTFILE.

QUAL--The qualify statement is used to qualify one value with that of another. When used with a parameter type of *NAME, it allows you to associate a qualified name with a parameter. You will reference a label inside the PARM statement, then define both the parameter and its qualified name at the label referenced in the PARM statement. The most widely used example of the QUAL statement is entering a library name, *LIBL, or *CURLIB to qualify where you want to look for a specific object. The QUAL statement even indents the qualified name a little when the command is displayed, so the user can understand the difference between that and a normal parameter.

Now that you have some basic knowledge of what goes into a command, let's take a look at a very simple one. DSPDTAQD is a command I wrote to display the information about a data queue. You will notice that I didn't use all the potential statements in this command. That's because I didn't have to. Just as with any language, you will probably employ 20 percent of the capabilities 80 percent of the time, and vice versa. Never fear, though, in a future article I will provide a more advanced command that will illustrate the use of every statement available. For now, I would like you to get a feel for how a command is constructed before moving on to the tougher stuff.

First, I code my CMD statement. The PROMPT text will display at the top of the command screen when the user types DSPDTAQD and presses the F4 key from a command line.

Next, I code my parameter for the data queue. Notice that I don't define the parameter type in this statement; rather, I reference a label called QUAL. The statements found at the QUAL label will now do the actual defining of the parameter. In the first QUAL statement, I define the original parameter as *NAME and further define that it cannot be left blank. I do this by providing the minimum (MIN) parameter with a value of 1. The next QUAL statement defines the qualified name--in this case, a library name. I also define some special values that can be entered in this qualified parameter, which may or may not match the type required in the qualified parameter itself. You probably recognize the special values of *LIBL and *CURLIB and understand what they do. The reason why they have to be defined as special values is that they break the rules of the *NAME type because they start with an asterisk (*).

That's all there is to it. You've entered the command statements. Now, before we compile our command, let's move on to some other steps.

The processing program is the program that will make your command tick. The command source doesn't really perform any logic. The processing program is where the logic for the command is run. In this example, the processing program is where the data queue information is retrieved and displayed on the screen. The processing program can be written in any language you choose--if that language compiles and runs on the iSeries, that is. It is linked to the command in the CRTCMD command, as you will see shortly. I am not going to say much about the processing program, because there is nothing special about it. It is a program like any other, except that it will be linked to a command. You can call this program directly, if you like, without using the command. The only thing I really need to mention is that the program must accept all the parameters used in the command. My command only has one parameter, the data queue you want to investigate. It may look like two parameters because you also have to enter the library where the data queue resides, but, if you remember from the previous paragraph, the library is a qualifier for the data queue parameter, and as such it becomes part of the parameter. So instead of two 10-byte parameters, the program accepts one 20-byte parameter that will be used to house the data queue and the library. I have included the program, DSPDTAQDRG, and its related display file, DSPDTAQDDF, as part of the download and for your viewing pleasure.

Including a validity checker with your command is optional, but it can be very helpful. In the last issue, I covered validity checking programs in detail and discussed the same validity-checking program I will use in this article, so I won't go over it all again. Please review that article, "Add Oomph to Your Commands with Validity Checking Programs," to get a firm grasp on validity checking programs.

Now that the command source has been written and the processing program and validity checkers have been written and tested, it's time to put it all together. CRTCMD (Create Command) allows you to do just that. It is the final piece of the puzzle. If you go back to your command source in PDM, place a 14 next to it and press F4, and you will be prompted with the CRTCMD command. There are a bunch of parameters you can enter in this command, but I am only going to discuss the ones necessary to get your command compiled. However, I invite you to check out the other parameters, which allow you to control such aspects as what environment you allow your command to be run in, whether you want to limit the users who can use the command, and how many positional parameters you allow to be entered when the command is run from the command line, without prompting.

First, you have to enter the name of your command and enter the library in which you want it to reside. Next, enter the program and library of the processing program you plan to employ. In my example, it is DSPDTAQDRG. Now you're done with the required parameters. Press F10 to display additional parameters and enter DSPDTAQDVC in the validity checking program parameter, VLDCKR . You don't have to do this, but this program will check to see if the data queue and library entered are valid. I've included the program with this article and a complete explanation can be found at the link provided in the Validity Checker section. That's it. Press Enter and you should now have a working command that you can use to display information about a data queue.

I have shown you the very basics of creating OS/400 commands. I invite you to explore further into the different options available. In fact, here's a homework assignment for you (don't worry, no need to turn it in). Take my command and add the option to select the output of the data. Take a look at DSPOBJD command as an example. You will have to modify the command source, the processing program, and the validity-checking program, but it will be a good exercise in creating commands, as well as a very nice feature of your command. In a future article, I will discuss some advanced concepts and show you a more complex command. In the meantime, do your homework!

Sponsored By

WORKSRIGHT SOFTWARE

CASS Certification
What is it? Why do you need it?

CASS stands for "Coding Accuracy Support System." This is a test developed by the U.S. Postal Service to determine whether ZIP Code software can accurately assign ZIP Codes to mailing addresses. CASS-certified software is intended to improve the accuracy of carrier route, 5-digit ZIP, ZIP+4, and delivery point codes.

CASS certified means the software has passed the test. When you use CASS software to update and maintain your mailing file, then your mailing file becomes CASS certified. What does this mean to you?

CASS certification is the first step in qualifying for postage discounts. Look at the mail you receive at home and at work; you will see that a lot of it was mailed for less than the regular 37 cent rate.

Despite all the glitz and glamour of the Internet, email, and such, the wheels of America's economy are lubricated by the ordinary envelope and the U.S. Postal Service.

If your company sends out a lot of mail, there is a good chance CASS certification can cut your postage expense. There are other steps you must perform to get these discounts, but CASS is the first step.

Your mail must be printed, sorted, and then packaged according to postal regulations. It takes some effort, but the potential savings make it worthwhile.

Exactly what happens when you process your mailing files with CASS software? The software breaks the address down into its individual elements: state, city, street name, and so forth. Then the information is compared to the national ZIP+4 database. If a match is found, the ZIP Code, ZIP+4, delivery point, and carrier route are assigned. Also the delivery line is standardized to comply with Postal Service preferences.

If an address can't be matched, no action is taken. This has the positive effect of allowing you to identify addresses in your mailing files which possibly can't be delivered, will be delayed in delivery, or at the very minimum need some minor correction to one of the address elements.

Using CASS certified software has many side benefits. You will be able to identify addresses that are potentially undeliverable. It has been estimated that as much as 30% of all advertising mail is never delivered.

That means the costs of postage, printing, paper, and overhead for undelivered mail are wasted. That means if you spend $100,000 on a direct mail campaign, as much as $30,000 could be completely wasted.

CASS software provides a number of intangible benefits. With CASS certification and bar coding there is a good likelihood that that your mail will be delivered sooner. If your invoices are delivered one day sooner, you may receive payment one day sooner.

If you CASS certify your mailing file, you can move on to the next step which is postal automation. This means applying a POSTNET bar code.

POSTNET is that little row of tall and short bars you see on your mail. POSTNET is a special bar code used by the Postal Service to allow automatic sorting machines to work.

It has been reported that bar code standard class (the old third class) mail gets delivered about as soon as first class, instead of the usual 2 or 3 weeks.

The bottom line is that using CASS software will help you keep your customers' address information in much better shape than they would be otherwise. Your mail may be delivered sooner at less cost and that means more bottom-line dollars for your company.

If you would like more information about CASS and CASS software,
contact your local post office or
call WorksRight Software, Inc. at 601-856-8337.

Are FedEx, United Parcel, and Airborne charges
for incorrect addresses eating into your budget?

Every bad address can result in a $5 to $10 charge. Even seemingly small addressing errors such as misspelled street names, or missing suite numbers can result in the same penalty as if the address were totally wrong.

Our PER/ZIP4 addressing matching software will match your addresses to the national ZIP+4 postal database. Based on the match PER/ZIP4, will update your addresses to postal standards. Our sophisticated address logic can add missing directionals, correct minor misspellings, and standardize the address format. If PER/ZIP4 can't match the address, then you know that there is likely a serious error in the address that needs to be corrected.

PER/ZIP4 can be used in a batch mode to update an entire file or interactively to update individual address one at a time. We provide a search function so that you can search the national ZIP+4 database to verify a specific address.

Visit our Web site www.worksright.com for more information and to order a free, no-hassle, 30-day trial. Or call WorksRight Software, Inc. at 601-856-8337.