Every iSeries and AS/400 (hereafter referred to as iSeries) comes with a program that runs automatically during a system IPL. This program is provided to perform such tasks as starting subsystems, starting TCP/IP services, and starting the system printers. IBM has granted you the right to modify the startup program by giving you access to its source code. In this article, Ill show you how to find the startup program on your system, and how to retrieve its source. After that, Ill take a look at the format of a typical startup program, and then Ill show you how to modify it to meet the needs of your individual shop.
Wheres the Source?
The default OS/400 startup program is named QSTRUP, and it resides in library QSYS. Its possible that, at some point in the past, you or someone else has changed the default startup program your system uses when it IPLs. That is, someone may have created a duplicate of the startup program, added some unique functionality, and then compiled it under a different name. To determine the name of the current system startup program, enter the Display System Value (DSPSYSVAL) command on an iSeries command line as shown:
DSPSYSVAL SYSVAL(QSTRUPPGM)
This command will display the name of the program, which is defined as the current system startup program. You can modify this program by retrieving its source code. To do so, enter the Retrieve CL Source (RTVCLSRC) command from an iSeries command line as shown:
RTVCLSRC PGM(pgmlib/pgmname) SRCFILE(yourlib/yourfile).
Remember to replace pgmlib and pgmname with the library and program names that were shown when you displayed the QSTRUPPGM system value earlier. You should issue this command every time you want to modify the startup program rather than using any existing source of the same name you may have found. This is because you never know if the source you discovered in the source file somewhere matches the current object. If it doesnt, you could be creating problems by starting services you no longer need or not
starting services that should be running. Be safe. Get a fresh copy of the source for the current startup program each time.
Figure 1 (page 110) is an example of the source from a typical startup program. Before you start modifying your own startup program, take a moment to study the source you retrieved. Look at the subsystems and other services that are currently being started. One thing you should notice is that there is a Monitor Message (MONMSG) command immediately following each command. The reason for this is so that if any single command fails during program execution, the rest of the program can still continue running. And, this is a critical requirement because you cant afford to have your system IPL fail due to a startup program not finishing! When you add your own commands or functions to the startup program, make sure that you monitor for any possible errors the commands or function can generate so that you dont inadvertently keep your system from starting. The easiest way to do this is to monitor for the message ID CPF0000 after each command. If the command fails, this will generally catch any exception errors, and then allow the program to continue on to the next command. You may be tempted to add a global error message monitor at the beginning of the program. Dont do it. If you do, and one of the commands in the program fails, the entire program will abend. And, if that happens, none of the commands that should have run after the failing command will be able to execute.
Modifying the Startup Program
In most cases you will want to place any additions to the program immediately after the DONE: tag line. It is possible that you would need to place commands in the section of the program before the DONE tag. For example, if you needed to complete a task prior to starting a specific subsystem, this would be inserted somewhere before the STRSBS command for that subsystem. One of the most common reasons to modify the startup program is to add a command to start your systems TCP/IP services or start all the Host Servers when the system starts. To accomplish this, you would probably add the following five lines of code to the program source:
QSYS/STRTCP
MONMSG MSGID(CPF0000)
QSYS/DLYJOB DLY(60)
QSYS/STRHOSTSVR SERVER(*ALL)
MONMSG MSGID(CPF0000)
Remember to place these lines immediately following the line containing the DONE: This code will start the TCP/IP interface, take a one-minute pause to wait for all of the TCP/IP services to become active and then start the host server jobs allowing PC clients to access the host resources. Once youve added these lines to the startup program, save your work and exit SEU. Next, you will need to compile the new, modified version of this program. Do this by entering the Create CL Program command (CRTCLPGM) from a command line as shown:
CRTCLPGM PGM(libname/QSTRUP) SRCFILE(libname/filename)
You will probably want to create the modified version in a library other than the library containing the original, unmodified program (QSYS). This will leave the original program untouched for later use. Also, once youve tested your startup program and are sure its ready to go, you can simply change the QSTRUPPGM system value to activate the new program. If you choose to upgrade to a new release. the unmodified startup program for that release would overwrite whatever version of the startup program exists in QSYS library. By keeping your new startup program in a different library or by giving it a name other than QSTRUP, you can ensure that the new program will remain as the current
tag.
startup program, even after an operating system upgrade. After your source has been saved and compiled, its time to think about testing the program and checking object authority on any added commands.
Object Security and Testing
Once youve modified the startup program, its important to make sure that any commands youve added will be able to be run when the startup job runs. One of the primary causes of a modified startup program failing is that the QPGMR user profile doesnt have authority to the command. To avoid this snag, you will need to make sure that the QPGMR profile has object authority on any commands youve added to the startup program, since the startup job itself runs under the QPGMR profile. When checking command authority, either *PUBLIC or QPMGR need to have at least *USE authority on any commands to be executed. To check or modify the object authority, use the Edit Object Authority (EDTOBJAUT) command as shown:
EDTOBJAUT OBJ(QSYS/STRTCP) OBJTYPE(*CMD)
The next step is to test your modified startup program. Believe it or not, testing your startup program is as simple as calling the program from a command prompt by issuing the command CALL PGM(mylib/QSTRUP). This is possible thanks to the MONMSG command that I mentioned earlier. Using this command prevents error messages from being returned if a job has already been started. This means that when you run the startup program you wont receive error messages when the program tries to start subsystems that are already active. The downside to simply calling the startup program from a command line is that, while you can test the program for functionality, it wont show any possible authority problems that could occur when the program is run at IPL under the QPGMR profile. The solution to that problem is to test the startup program by submitting the CALL command so that it runs using the QPGMR profile. The syntax for that command is as follows:
SBMJOB CMD(CALL PGM(mylib/QSTRUP)) USER(QPGMR)
Preventing the Startup Program from Running
You may have a legitimate need to not run the startup program during an IPL. Perhaps you are installing new DASD or other hardware, and you need to perform multiple IPLs. In that case, you may not want to wait for the startup program to finish running each time before you can IPL again. In that case, you should have an understanding of how the startup program is executed so that you can keep it from running.
The system startup program runs as an autostart job after the iSeries has finished IPLing and, more specifically, after the controlling subsystem, QCTL, has started. In the subsystem description for QCTL, youll find an autostart entry named QSTRUPJD. If you issue the command Display Job Description (DSPJOBD) command for the QSTRUPJD job description, youll see that the Request Data entry reads QSYS/CALL QSYS/QWDAJPGM. It is the QWDAJPGM program that retrieves the system value QSTRUPPGM and then runs the program defined there. If you want to keep the startup program from running, then you must ensure that the system value QSTRUPPGM contains the special value of *NONE. When the QSYS/QWDAJPGM program runs, it will find *NONE as the name of the program to run and immediately terminate. To change this system value, enter the Change System Value (CHGSYSVAL) command as shown:
CHGSYSVAL SYSVAL(QSTRUPPGM) VALUE(*NONE)
On Your Marks...
Using the information shown here, you should be able to accurately simulate how the startup program will run at IPL. Its important to remember that, by default, the job description used by the startup program does not log CL commands. If you are experiencing problems with your startup program or if you want to monitor the startup program after making a modification, you can simply change the QSTRUPJD job description to log CL commands. This would be done using the Change Job Description (CHGJOBD) command as shown:
CHGJOBD JOBD(QSTRUPJD) LOGCLPGM(*YES)
After your system has IPLed and the startup job is complete, you will find the job log from this program in the QEZJOBLOG output queue. At this point, your modified startup job should be thoroughly tested and ready to go. All you need to do now is change the QSTRUPPGM system value by using the Change System Value command mentioned previously and entering the library and name of your new startup program in the VALUE parameter. With a little modification and some careful preparation and testing, you can easily automate the running of any required programs when your system IPLs.
REFERENCES AND RELATED MATERIALS
OS/400 Work Management V4R4 (SC41-5306-03, QB3ALG03)
PGM
DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)
DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)
DCL VAR(&CPYR) TYPE(*CHAR) LEN(90) VALUE('5769-SS1 (C) COPYRIGHT-
IBM CORP 1980, 1999. LICENSED MATERIAL - PROGRAM PROPERTY OF IBM')
QSYS/STRSBS SBSD(QSPL)
MONMSG MSGID(CPF0000)
QSYS/STRSBS SBSD(QSERVER)
MONMSG MSGID(CPF0000)
QSYS/STRSBS SBSD(QUSRWRK)
MONMSG MSGID(CPF0000)
QSYS/RLSJOBQ JOBQ(QGPL/QS36MRT)
MONMSG MSGID(CPF0000)
QSYS/RLSJOBQ JOBQ(QGPL/QS36EVOKE)
MONMSG MSGID(CPF0000)
QSYS/STRCLNUP
MONMSG MSGID(CPF0000)
QSYS/RTVSYSVAL SYSVAL(QCTLSBSD) RTNVAR(&CTLSBSD)
IF COND((&CTLSBSD *NE 'QCTL QSYS ') *AND (&CTLSBSD *NE-
'QCTL QGPL ')) THEN(GOTO CMDLBL(DONE))
QSYS/STRSBS SBSD(QINTER)
MONMSG MSGID(CPF0000)
QSYS/STRSBS SBSD(QBATCH)
MONMSG MSGID(CPF0000)
QSYS/STRSBS SBSD(QCMN)
MONMSG MSGID(CPF0000)
DONE:
QSYS/RTVSYSVAL SYSVAL(QSTRPRTWTR) RTNVAR(&STRWTRS)
IF COND(&STRWTRS = '0') THEN(GOTO CMDLBL(NOWTRS))
CALL PGM(QSYS/QWCSWTRS)
MONMSG MSGID(CPF0000)
NOWTRS:
RETURN
CHGVAR VAR(&CPYR) VALUE(&CPYR)
ENDPGM
Figure 1: The retrieved startup program should contain the MONMSG command.
LATEST COMMENTS
MC Press Online