The Four Hundred

I recently modified an OS/400 system start-up program (QSTRUP) to start another process at system start-up. My program didn't start correctly, and I found myself scrambling to find the QSTRUP job log in order to correct the error. For this issue, I thought it would be interesting to review the QSTRUP procedure and to show you how to find this information when your QSTRUP programs go bad.

Trying to locate start-up program information is interesting because of the way OS/400 runs its system start-up program and because the way that people code start-up program changes masks execution errors that occur in QSTRUP. Let's take a quick look at the process that OS/400 uses to start your system, where the process fails when there's an error, and how you can locate the QSTRUP job log.

As you may know, OS/400 stores the name and library of its system start-up program in the QSTRUPPGM system value, which you can view and change by using the following Work with System Value (WRKSYSVAL) command:

In the Operations Navigator program that comes with Client Access Express for Windows V5R1, you can find and modify the QSTRUP name by clicking your iSeries or AS/400 box, under My Connections, and then opening the following Configuration and Service-System Values-Restart path. This brings you to the Restart System Values screen, where the start-up program name is listed under the Setup tab.

The shipped value for the program name is QSTRUP (a CL program), residing in the QSYS library. OS/400 calls QSTRUP when its controlling subsystem--as defined in the QCTLSBSD controlling subsystem's system value--starts. The program runs automatically in the controlling subsystem, kicking off all the services and other subsystems that your iSeries or AS/400 needs. Many shops retrieve and modify the QSTRUP code, compile the changed code into another library (such as QGPL), and then change the QSTRUPPGM system value to point to the modified program, which then runs at system start-up in place of the default.

The problem, of course, is debugging the changed code. Because QSTRUP contains commands that are run only at start-up, there's no easy way to test your changes, short of a system restart. And because QSTRUP runs before everything else starts in OS/400, it's essential to trap errors that could stop program completion. That's why the traditional way of coding QSTRUP calls is to enter two lines for each command or program call: one line for the command or call itself and a second line to trap errors by using a Monitor Message (MONMSG) command, as follows:

Working in tandem with the call, the MONMSG line provides an error-recovery feature. Message ID CPF0000 traps most errors, so QSTRUP will move on to the next statement and continue to run, even when something goes wrong. In this way, your QSTRUP program is guaranteed to end--which is quite practical, to avoid having your start-up program hang while it is waiting for an error-message reply. The downside of using paired-call and MONMSG statements is that QSTRUP errors are frequently missed because the program itself covers up coding or execution mistakes.

That's why you need to check the QSTRUP job log to ensure that all the commands you entered were processed. The key to finding the job log is to understand that the start-up program runs under the QPGMR user profile. Furthermore, QSTRUPJD is the name of the job that runs the QSTRUP program inside the controlling subsystem. With this information, you can locate your job log by first displaying all the system jobs that belong to QPGMR, which is done by running the Work with User Jobs (WRKUSRJOB) command, as follows:

WRKUSRJOB produces a list of QPGMR jobs whose output is still present in the system. Page down to the most recent job called QSTRUPJD (usually the last QSTRUPJD entry in the list) and enter 5 (work with job) in front of that entry. This brings you to the Work with Job screen for your latest system start-up job. Here you can enter 4 (work with spooled files) at the command line to view the job's spool files, including your QSTRUP job log. You can then analyze the results of your QSTRUP changes and make code adjustments for the next time you restart your system.

I tested using WRKUSRJOB to find QSTRUPJD on an OS/400 V4R5 system and an OS/400 V5R1 system, and there is no difference in retrieving this information for either version.

Changing and testing your QSTRUP program isn't the most efficient process in the world, but if you know where to find your job log information, it becomes a little easier when you can at least identify your mistakes.