Admin Alert: A Primer for Changing Your i5/OS Startup Program

Published: September 12, 2007

by 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.

1. Finding your startup program object
2. Finding the startup program's source code
3. Archiving your old startup program object and source code
4. Changing the startup program code
5. Compiling and identifying your new startup program to the system
6. Monitoring the results

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).

DSPSYSVAL SYSVAL(QSTRUPPGM)

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.

• Qualify all commands and program calls - Make sure that you qualify any libraries that a program or command is called from. The startup program is run under the QPGMR user profile and the additional commands or calls you are adding may not be available in the job's library list. So always qualify program and command calls with the library name where they reside to make sure that the startup program can find them.
• Always monitor for error messages - To ensure that the QSTRUP program finishes no matter what errors occur, IBM always follows every statement in their default program with a Monitor Message command (MONMSG) that monitors for operating system message CPF0000. CPF0000 is a generic message that i5/OS issues whenever any program error occurs. Monitoring for CPF0000 tells your startup program to ignore the message the program is generating and to process the next command. This allows the program to run to completion without hanging up while waiting for a message reply. When you do this in the QSTRUP program, all program calls or commands should be directly followed by a MONMSG command, see the sample code below. (If you don't use this MONMSG technique, your startup program could fail with an error and wait on a system message reply without bringing your system up, which can be a tricky situation to maneuver.)

CALL lib_name/program_name or i5/OS Command

MONMSG MSGID(CPF0000)

• Place all new commands or program calls at the bottom of the program - This will ensure that most of your startup processing will still occur even if the new command crashes or enters into a looping state. Doing this will also give any pre-requisite i5/OS servers, such as the Host Servers or TCP/IP servers, a chance to start before the new code executes.
• Compensate for QPGMR's lack of authority in running new code - As I said, the startup program runs under QPGMR's user profile so you have two choices regarding program authority. You can either authorize QPGMR to execute the new code or you can program your QSTRUP program to submit the new code as a batch job that will run under another authorized user profile. If you want to submit code or a program to a batch job queue from QSTRUP, you can add a Submit Job command (SBMJOB) to your code that is similar to the code below. By doing this, the program will run in batch under the authority of the user profile name listed in the SBMJOB User parameter (USER). Be careful, however, that QPGMR has the authority to submit jobs under another user profile name.

SBMJOB CMD(CALL PGM(library/program_name) JOB(STARTUPJOB) JOBQ(QGPL/QBATCH) USER(running_user_name)

MONMSG MSGID(CPF0000)

• Comments are optional but they may not last forever -- Code comments are a staple of good programming but they can easily get lost in a QSTRUP program if someone uses the RTVCLSRC command to retrieve the code at a later date. When RTVCLSRC returns source code, it strips out any comments that the program was originally compiled with. So one of the realities of modifying your QSTRUP program is that you may or may not be able to retain your comments depending on how the source code is retrieved and modified in the future.

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).

WRKSYSVAL SYSVAL(QSTRUPPGM)

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.

RELATED STORY

Where's My QSTRUP Start-Up Job?

                     Post this story to del.icio.us
               Post this story to Digg
    Post this story to Slashdot