Admin Alert: How to Change Your OS/400 Startup Program

by Joe Hertvik

In an earlier Admin Alert, I explained how to locate your OS/400 startup program job log to correct execution mistakes in your startup routine. If you're not familiar with changing the OS/400 startup program, it can be confusing, because the documentation isn't easily found and most people will change the program only once in a great while. I thought it would be helpful to look at how to create a new OS/400 startup CL program this week.

There are a few tricks and techniques for avoiding execution mistakes within the program. You can use this information as a checklist for modifying your OS/400 startup routine.

The name and location of your startup program is found in the QSTRUPPGM system value, and you can retrieve the name and library of the startup program (QSTRUP) by executing the following Display System Value (DSPSYSVAL) command:

DSPSYSVAL SYSVAL(QSTRUPPGM)

(For more information about QSTRUPPGM and the QSTRUP program, see "Where's My QSTRUP Start-Up Job Log?" as well as the follow-on article, "Readers' Insights on Inactive Jobs and QSTRUPJD Job Logs.")

To retrieve the most recent copy of your startup program CL code, use the Retrieve CL Source (RTVCLSRC) command to put a copy of the startup program's source code into an OS/400 source file. So if your startup program name was QSTRUP, in library QSYS (OS/400's default startup program, which is shipped with the machine), you could retrieve its CL source code into the QCLSRC source file in library QGPL by executing this RTVCLSRC command:

RTVCLSRC PGM(QSYS/QSTRUP) SRCFILE(QGPL/QCLSRC)

Once the code is retrieved, you can make your changes to member QSTRUP in source file QGPL/QCLSRC. You can add any additional subsystem startup commands, program calls, submit job statements, or any other CL commands you want to execute when the system is restarted after an IPL.

As you edit your startup program, however, be careful to avoid the following common startup program coding mistakes.

Be sure to qualify the library your CL commands or programs reside in. Your QSTRUP program is generally run under the QPGMR user profile and any commands you add to QSTRUP may or may not be in the user or system part of the startup job's library list. To ensure that the system can find your intended command or program name, always qualify it with the library it resides in. For example, if you were adding a call to a third-party vendor program called FAXPROGRM in FAXMIDRNG library, to your startup program, stay away from entering the command without a qualifying library, like this:

CALL PGM(FAXPROGRM)

The QSTRUP job may not be able to find this program at execution time. Rather, enter the program name with the qualifying library name, like this:

CALL PGM(FAXMIDRNG/FAXPROGRM)

In addition to qualifying the library so the program can find the object, make sure to put in a Monitor Message (MONMSG) command for message ID CPF0000 after each command or call statement, like this:

CALL PGM(FAXMIDRNG/FAXPROGRM)
MONMSG   MSGID(CPF0000)

Message ID CPF0000 monitors for any OS/400 errors that may occur once the FAXMIDRNG/FAXPROGRM program is executed. It also tells your QSTRUP program to ignore the error and to continue executing with the next available statement. This is the traditional way of coding QSTRUP command and program call statements. MONMSG's job is to trap most errors, so QSTRUP will move on to the next statement and continue to run, even when something goes wrong. The downside of using paired-call and MONMSG statements like this, however, is that QSTRUP errors are frequently missed because the program itself covers up coding or execution mistakes.

Make sure that the QPGMR user profile (or the user profile you run the QSTRUP program under) has authority to run your target command or program. You can check the authority of the program or command by running the green-screen Edit Object Authority (EDTOBJAUT) command. For our FAXPROGRM example, you would run EDTOBJAUT as follows:

EDTOBJAUT OBJ(FAXMIDRNG/FAXPROGRM) OBJTYPE(*CMD)

To run a program or command, the target user must at least possess *USE authority or above for the object.

Make sure that any Submit Job (SBMJOB) commands you specify in your QSTRUP program are run under a user profile that has authority to all the programs and objects the submitted job needs. You do this by specifying a valid user name in the USER parameter of your SBMJOB statement. So if you wanted to submit your FAXPROGRM call as a submitted job from your QSTRUP program, you enter the SBMJOB command like this:

SBMJOB CMD(CALL PGM(FAXMIDRNG/FAXPROGRM)) JOB(FAXSTARTUP) 
MONMSG   MSGID(CPF0000)

The submitted job will then run under the authority of the user profile of the user who is running the QSTRUP program (which is QPGMR, by default). However, QPGMR may not have all the necessary authorities to run FAXPROGRM, so if you wanted to run the program under the FAXUSER user profile, to ensure proper authorities, you would modify the code this way:

SBMJOB CMD(CALL PGM(FAXMIDRNG/FAXPROGRM)) JOB(FAXSTARTUP)  + 
USER(FAXUSER)
MONMSG   MSGID(CPF0000)

And the program will run under the proper user name.

Once you've programmed the new QSTRUP program and want to compile and use it, I recommend a two-step process. First, don't compile the new QSTRUP program to library QSYS. Compile it to another library, such as QGPL. Doing this preserves IBM's original QSYS/QSTRUP program in case you ever want to use the original program again as your startup program (such as when you're performing an OS/400 upgrade and want to run a simpler QSTRUP program during the upgrade). You may also want to save a copy of the original program to another library or tape in case the program is accidentally deleted.

After you've compiled the program correctly, and you want to specify your changed program as the new QSTRUP program, you can execute the following Work with System Values (WRKSYSVAL) command and then use an option '2'=Change to specify the name and library of your new QSTRUP program.

WRKSYSVAL SYSVAL(QSTRUPPGM)

Then the next time you perform a system IPL, or restart your iSeries or AS/400 controlling subsystem, the system will use your new program.

Sponsored By ITERA

Reorganize While Active! Now you can recover deleted record space without locking users out of your files when you reorganize them. With iTera's new Reorganize While Active™ solution, you can reorganize any size file with just a few seconds of downtime--whether the file is 5 GB in size or 100 GB! Want to help your company eliminate downtime? Email us at info@iterainc.com or call 800-957-4511 or visit us at www.iterainc.com