If you've ever had a program fail because of the dreaded CPF4131 level-check error, you know how frustrating this can be. These messages are generated when a called program attempts to access files whose level is different from the level in place when the program was compiled. This problem is easy enough to correct by recompiling the program or by using the LVLCHK(*NO) option when you create the file or write an override statement.

Having said that, these solutions may not always be an option. Wouldn't it be nice if there were an easy way to determine if a program was compiled over a different record format level than the record format level of the file that it's going to be run against? That's where the WRKPGMFLVL command comes in. This utility allows you to compare the record format levels for all files within a given program against the record format levels for the files within a specified library and/or library list.

Why Level Check?

At this point, you may be thinking that the solution is to simply compile all of your files—physicals, logicals, printer files, and display files—with the LVLCHK(*NO) option. While this solution will work in some cases, it won't always work and can, in fact, cause the program to fail as a result of bad data (e.g., decimal data errors). Even worse, the program may execute without a problem, but the data may be read from the file incorrectly.

The Solution

One solution to this problem is to periodically check programs against the environment in which they are run to determine if any potential record format level-check conditions exist. This would normally require you to use the Display Program Reference (DSPPGMREF) command for each program to be checked and then compare the record format level for each file within the program with the actual file on your system. This process would be very laborious and nearly impossible to complete for more than a few programs at a time.

That's where the WRKPGMFLVL command comes in. This utility gives you the ability to determine whether programs have any potential level-check conditions based on a defined library list. This means that, by using this utility, you can check against multiple environments that may exist on your system: test and production, for example. The utility output can be directed to one of multiple locations to meet different requirements. In interactive mode (*), the utility can be run against a single program to display information specific to that program.

In printed output mode (*PRINT), the program can be run against a single program or a group of programs based on a wildcard value or against all programs in a given library or library list. As the name suggests, output from this option is generated as a printed report containing all of the record format level information for each program. Multiple programs can also be selected when the output mode is sent to a physical file (*OUTFILE). This option outputs all of the same information contained within the printed report, but the data is saved in a defined physical file. The final mode, *JOBLOG, allows you to simply send messages to the job log indicating which programs and files within a defined list have level-check conditions. This option can be extremely useful when creating an installation utility to install or upgrade applications on a new system.

Figure 1 below shows the initial prompt screen for the WRKPGMFLVL command.

Figure 1: This is the prompt screen for the WRKPGMFLVL command. (Click images to enlarge.)

In addition to the options described earlier, you'll notice here that the WRKPGMFLVL command contains additional parameters, as described below:

When this command is executed in interactive mode, the screen displayed gives information about each file and record format used within the program. The output resembles that shown in Figure 2 below.

Figure 2: This is the interactive screen for WRKPGMFLVL command.

Notice that the screen displays a reverse image for record formats where level checks exist or where the record format doesn't exist in the defined library list. You can use the F14 key to toggle between displaying level checks only and all records. There is also a "Position to" field at the top of the screen that allows a user to specify a file name to be positioned to. This is useful when multiple screens of record formats are displayed.

The Code

This utility is made up of several programs and files that can be downloaded here. The table below contains a list of the objects required for the WRKPGMFLVL command.

An Ounce of Prevention

The WRKPGMFLVL utility will do many things to help you to prevent level-check conditions from occurring when you least expect it. There are a few things, however, that this utility won't catch. Files accessed through embedded SQL statements are not returned by the DSPPGMREF command and as a result are not displayed in the WRKPGMFLVL utility. This utility also does not display record format level-check information for externally described data structures. This can be more of a problem than embedded SQL since an undetected change to an external data structure has a greater potential to adversely affect program results.

These shortcomings aside, the WRKGPMFLVL utility can be a lifesaver, and it makes a great addition to your programming toolkit.

Mike Faust is a Business Analyst for Invivo Corp. in Orlando, Florida. Mike is also the author of the books The iSeries and AS/400 Programmer's Guide to Cool Things and Active Server Pages Primer and SQL Built-in Functions and Stored Procedures. You can contact Mike at mikeffaust@yahoo.com.