Admin Alert: A Primer for Changing Your i5/OS Startup Program
September 12, 2007 Joe Hertvik
At some point, all System i and iSeries administrators will need to add new functionality to their system startup program (QSTRUP). While it’s easy to change and recompile QSTRUP, there are a few pitfalls to avoid so that the new code executes properly and so that it doesn’t hang the system in error. To help you understand QSTRUP modification, here’s my primer on locating, changing, and compiling your startup program.
Changing the QSTRUP startup program consists of the following six simple steps.
These steps are routine but there are a few snake traps to beware of. Changing QSTRUP source code on an i5/OS or OS/400 system is tricky because you can’t truly test the code unless you IPL the partition. So you have to be fairly methodical to avoid obvious mistakes that must be manually corrected after startup or mistakes that could hang your system startup program before it finishes starting the system.
Step 1: Finding Your Startup Program Object
The first step in changing your startup program is determining what program i5/OS runs at system startup and where the program is located. In i5/OS and OS/400, your partition’s program startup name and location can be found in the Startup Program system value (QSTRUPPGM). You can display that program name by running the following Display System Value command (DSPSYSVAL).
If you’re using iSeries Navigator, you can find and change this value by opening the Configuration and Service→System Values node for your system i partition and then selecting the Restart option from the System Values pane on the right-hand side of the screen. Click on the Setup tab in the Restart System Values Window that appears and you will see your startup program name and the library that it resides in.
Step 2: Finding the Startup Program’s Source Code
As shipped, the default i5/OS startup program object is QSTRUP and IBM stores that object in the QSYS library. According to some sources, IBM delivers the QSTRUP source in the QCLSRC source file in the QGPL library. However, if your shop has been running i5/OS (or its predecessor OS/400 operating system) on this partition for a number of years, chances are good that someone along the way has modified the program so that the original source code may no longer be valid. To make sure that you are working with the right source code, there are two ways to locate or retrieve the current source code for your startup program.
The first way is to retrieve the source code location from the program object information that was stored with the startup program when it was compiled. To get this information, you can run the Display Program Information command (DSPPGM) for your QSTRUP program, like this:
DSPPGM PGM(startup_program_library/startup_program_name) DETAIL(*ALL) =
On the first DSPPGM screen, you’ll see the location and library of the source code that was used to create the program. If you can’t find the source location from DSPPGM, you can retrieve also retrieve the source into a source code file member by using the following Retrieve CL Source command (RTVCLSRC).
RTVCLSRC PGM(startup_program_library/startup_program_name) SRCFILE(source_file_library/source_file_name)
And this command will retrieve the current source code for your startup program, which can then be modified to add in any other programs or commands that must be run at system startup.
Step 3: Archiving the Old Startup Program and Source Code
Before you change your startup program, I find that it’s valuable to make a copy of the original program object and source code. This is needed because there isn’t a good way to test QSTRUPPGM changes. You can only run them live. If you make a mistake in your changes and you need to restore the original program, you can always recompile the program with the old source code or replace the new object with the original object to back out any flawed changes.
Regarding source code, I usually copy the source to another source file member and I name the archived source file member with the last date that the prior QSTRUP code was active. So if I modify my startup program code on September 5, 2007, I would first copy my old startup source to a different source code file member named STARTU090507. This leaves me free to recompile the program (if I need to) with the prior source if the new code doesn’t work on the next system startup.
Similarly, I can also save the replaced startup program object with a different name (QSTRUP0905), in case I want to delete the revised program object and rename my saved program object back to the QSTRUP name.
Step 4: Changing the Startup Program Code
Once you have found the source code you want to modify, it’s a simple matter to add new code and to recompile your startup program. However, there are a few techniques that you should follow to make sure the code can properly run at system startup. To that end, here are my suggestions for the best way to change i5/OS startup program code.
CALL lib_name/program_name or i5/OS Command
SBMJOB CMD(CALL PGM(library/program_name) JOB(STARTUPJOB) JOBQ(QGPL/QBATCH) USER(running_user_name)
Step 5: Compiling Your Startup Program
Once you’ve made your QSTRUP source code changes, it’s time to compile the program. There are just three simple rules to follow when compiling.
First, don’t compile the source code as program object QSTRUP in the QSYS library. As mentioned earlier, this is the default location of the system’s shipped startup program and you will want to leave this program intact for reference or possible execution at a later date. Second, be sure to compile the program so that the QPGMR user can access and run this object, since the startup program runs under the QPGMR user profile.
Third, if you change the name or location of your QSTRUP program, be sure to also change the value of the Startup Program system value (QSTRUPPGM) to that name and location or your newly compiled code will not execute during the next system IPL. To change the location on the green screen, run the following Work with System Values command (WRKSYSVAL).
When the Work with System Values screen comes up, select option 2=Change and change the program name or location to fit your new object.
You can also change this value in OpsNav by opening the Configuration and Services→System Values node under the System i partition that you are working with. Once the System Values categories are displayed in the right-hand pane of the OpsNav screen, click on the Restart entry and select the options that are displayed under the Setup tab in the Restart System Values window that appears. Using this window, you will be able to see and change your start-up program name or the library that the program resides in.
Step 6: Monitoring the Results
At this point, your job is finished and you’ve successfully recompiled your system startup program. However, the job isn’t quite finished yet. You won’t know if you changes are effective until the next time you IPL your system and you can see the results of the new program running. During the IPL, you can try to watch the system startup job as it runs or you can view the results by checking out the QSTRUP job log, which will list out any errors or problems that occurred the last the system startup program was running.
As you can see, changing your system startup program is not a big deal. Like most things in i5/OS, it’s easy to accomplish if you just follow the right instructions.
About Our Testing Environment
Configurations described in this article were tested on an i5 550 box running i5/OS V5R3. Most of these commands shown here are also available in earlier versions of the operating system running on iSeries or AS/400 machines. The iSeries Navigator function was tested with the OpsNav program that comes with iSeries Access for Windows V5R3M0. If a command or function is present in earlier versions of the i5/OS or OS/400 operating systems, you may notice some variations in the pre-V5R3 copies of these commands. These differences may be due to command improvements that have occurred from release to release.