Changing the IPL Start-Up Program

Resolving The Problem

General Information About the Start-Up Program

The system IPL start-up program is run by an autostart job that runs in the controlling subsystem. This autostart job transfers control to the program specified in system value QSTRUPPGM. This autostart is run when the controlling subsystem is initially started using an IPL or is restarted using the STRSBS command after the system has been in restricted state. The name of the start-up job when it runs is the same as the name of the job description that the job runs with (QSTRUPJD). This job description resides in library QSYS and is initially set with the Log CL Program Commands parameter set to *NO.

The system default name of the IPL start-up program is QSTRUP in library QSYS. A default QSTRUP program is released with each new version of the operating system. If the system value QSTRUPPGM has not been changed on a particular system, when a new release is installed, the new version of the QSTRUP program released with the new set of system software is used as the IPL startup program for the system. This means that if a customer changes the start-up program but does not change the name of the program or the library it is in (leaving the system value unaltered), the modified version of the program is not used after the release upgrade. The old version of the program resides in the QSYSVxRxMx library where VxRxMx specifies the previous version/release/modification level.

If you suspect any problems with the start-up program, review the job log for the start-up program. To review the job log for the start-up program, on an operating system command line, type the following:

WRKJOB QSTRUPJD

Press the Enter key, and select one of the jobs in OUTQ status and view the spooled file QPJOBLOG for the job. If the QSTRUPJD job is active, select the option to view the job log of the job, and press the F10 key. Page up to view the entries in the job log. To pursue problems with the start-up job, use the CHGJOBD command to change the QSTRUPJD job description to set the Log CL Program Commands parameter to *YES. This provides better logging of information needed to resolve the problem.

Retrieving the CL Source of a Start-Up Program

Usually the file QCLSRC in library QGPL is used for this purpose; however, you may use a different source file if you wish. If you wish to use a particular source file and it already has a QSTRUP member of type CLP then you might want to retrieve the source into a new member and compare it with the source in the existing QSTRUP member. The source file must exist prior to executing the retrieve command or the command will fail. The following command may be used to create a new source file if needed.

CRTSRCPF FILE(mylib/myfile)

To retrieve the CL source of the start-up program for the system, on an operating system command line type the following:

RTVCLSRC PGM(QSYS/QSTRUP) SRCFILE(mylib/myfile)

Press the Enter key.

Note that the PGM parameter as shown above assumes that you want to retrieve the CL source of the QSTRUP program from the QSYS library (the version that comes with the release of the system). To retrieve the CL source of the current startup program for the system, display the QSTRUPPGM system value to check what it is, and change the PGM parameter as needed.

Viewing and Changing the QSTRUP Program Source

The QSTRUP program source may be viewed and changed using the Application Development ToolSet/400 - SEU utilities that are installed as part of Licensed Program 5722WDS. To start the utility, use the STRPDM command. This gives you a menu of options for IBM OS/400 or IBM i5/OS Programming Development Manager (PDM). Type 3 on the command line (Work with members), and press the Enter key. You are shown a screen, Specify Members to work with. Type the name of the source file to be used, the name of the library the file resides in, and use *ALL for the Member Name and Type. Press the Enter key to display the list of members. The QCLSRC source file in QGPL is already on your system. Therefore, if you do not have a particular source file you want to use, you may use QCLSRC. You may also use the EDTF command.

If there is no QSTRUP program listed of type CLP, retrieve the source for QSTRUP using the RTVCLSRC command as shown above. If the RTVCLSRC command is used to retrieve a source of a program after you already have a list of members displayed from a source file, press the F5 key to refresh the list so the new member is listed with the other previous members.

If your member list shows more than one QSTRUPxx member and you are not sure just which source member reflects the start-up program in use on your system, retrieve the member into a member with a different spelling for the name and compare it with your existing members.

To view a particular member, type 5 as the OPT for that member, and press the Enter key. This causes the member to be displayed. To edit/change a particular member, type 2 as the OPT for that member, and press the Enter key. The source of the member is displayed.

The following shows the code portion of the QSTRUP program shown on your screen. This version of the program is what was released with iSeries V5R3M0, V5R4M0, and V6R1M0.

0021.00      PGM                                                              
0022.00      DCL VAR(&STRWTRS) TYPE(*CHAR) LEN(1)                              
0023.00      DCL VAR(&CTLSBSD) TYPE(*CHAR) LEN(20)                            
0024.00      DCL VAR(&CPYR) TYPE(*CHAR) LEN(90) VALUE('5722-SS1 (C) COPYRIGHT-
0025.00  IBM CORP 1980, 2000. LICENSED MATERIAL - PROGRAM PROPERTY OF IBM')
0026.00      QSYS/STRSBS SBSD(QSERVER)                                        
0027.00      MONMSG MSGID(CPF0000)                                            
0028.00      QSYS/STRSBS SBSD(QUSRWRK)                                        
0029.00      MONMSG MSGID(CPF0000)                                            
0030.00      QSYS/RLSJOBQ JOBQ(QGPL/QS36MRT)                                  
0031.00      MONMSG MSGID(CPF0000)                                            
0032.00      QSYS/RLSJOBQ JOBQ(QGPL/QS36EVOKE)                                
0033.00      MONMSG MSGID(CPF0000)                                            
0034.00      QSYS/STRCLNUP                                                    
0035.00      MONMSG MSGID(CPF0000)                                            
0036.00      QSYS/RTVSYSVAL SYSVAL(QCTLSBSD) RTNVAR(&CTLSBSD)                
0037.00      IF COND((&CTLSBSD *NE 'QCTL      QSYS      ') *AND (&CTLSBSD *NE-
0038.00  'QCTL      QGPL      ')) THEN(GOTO CMDLBL(DONE))                    
0039.00      QSYS/STRSBS SBSD(QINTER)                                        
0040.00      MONMSG MSGID(CPF0000)                                            
0041.00      QSYS/STRSBS SBSD(QBATCH)                                        
0042.00      MONMSG MSGID(CPF0000)                            
0043.00      QSYS/STRSBS SBSD(QCMN)                            
0044.00      MONMSG MSGID(CPF0000)                            
0045.00 DONE:                          
0046.00      QSYS/STRSBS SBSD(QSPL)                                            
0047.00      MONMSG MSGID(CPF0000)                                
0048.00      QSYS/RTVSYSVAL SYSVAL(QSTRPRTWTR) RTNVAR(&STRWTRS)
0049.00      IF COND(&STRWTRS = '0') THEN(GOTO CMDLBL(NOWTRS))
0050.00      CALL PGM(QSYS/QWCSWTRS)                          
0051.00      MONMSG MSGID(CPF0000)                            
0052.00 NOWTRS:                                                
0053.00      RETURN                            
0054.00      CHGVAR VAR(&CPYR) VALUE(&CPYR)    
0055.00      ENDPGM                            

No changes should ever be made to the program after the RETURN statement at line number 0053.00 because they are not run. Using the example above it is pertinent to note that the statement numbers 0041 through 0046 are run only if the controlling subsystem is QCTL and its subsystem description resides in library QSYS or QGPL. Therefore, changes made to the startup program after line number 0044.00 and prior to the DONE label at line 0047.00 should be made only if the QCTLSBSD system value is set to QCTL. However, if QCTLSBSD is set to a subsystem other than QCTL (QBASE, for example), the statements in this section do not run. Making the changes after the DONE label at line 0047.00 and before the starting of print writers related code at line 0048.00 results in the code being run no matter what the setting of the QCTLSBSD system value.

To type one or more new statements after a particular line in the program source, type the letter I in any of the first 7 line number characters at the beginning of the line, and press the Enter key. For example, type I over the first 0 of the 0044.00 line. You are shown a blank line where you can type the new command. Press F4 to prompt for the various parameters of the command. After typing the command, press the Enter key. You are shown a new blank line. When you press the Enter key after not typing anything on the new blank line, the blank line is deleted. It is recommended that a MONMSG MSGID(CPF0000) command be added after each new line added to start another subsystem, start TCP, or whatever other type of start is needed. This MONMSG statement monitors for all CPFnnnn errors and permits the program to continue if a CPFnnnn error is posted.

Example

The following illustrates the lines you might add to start two additional subsystems:

STRSBS SBSD(QGPL/QINTER2)
MONMSG MSGID(CPF0000)
STRSBS SBSD(QGPL/QSNADS)
MONMSG MSGID(CPF0000)  

Starting TCP/IP

There is an IPL attribute to start TCP/IP. This IPL attribute can be accessed through the Display IPL Attributes (DSPIPLA) and Change IPL attributes (CHGIPLA) commands. The attribute allows for the starting of TCP/IP after the system IPLs or comes out of restricted (RSTD) state, and newly installed systems will have the attribute set to *YES. Setting this attribute to *YES will cause a batch job to be submitted to QSYSNOMAX in QSYSWRK. This batch job runs the STRTCP command. Note that this batch job is submitted to run using profile QPGMR. Changing the job description that it runs under by specifying a different profile name will not enable the job to run under that profile. The job description is QSYS/QTOCSTRTCP.

The recommendation by IBM Support is to use the IPL Attributes to start TCP/IP. There may still be some instances where the IPL attribute cannot be used and the STRTCP command in the system startup program should be used instead. For additional information, you should refer to Rochester Support Center knowledgebase document N1014291, Starting TCP - Using the IPL Attributes Versus the System Startup Program:


Authorization Considerations

Whenever any new commands are added to the startup program that were not previously used by the startup program, verify if QPGMR user profile is authorized to the command. This is necessary, as the startup program runs under the QPGMR profile. To check a specific command, on the operating system command line type the following:

EDTOBJAUT

Press F4 to prompt. Type the name of the command (for example, STRTCP), the name of the library (normally QSYS), and *CMD as the object type, and press the Enter key. If *PUBLIC authority is listed as *EXCLUDE and there is no existing private authority for QPGMR, *PUBLIC authority must be changed to *USE or press F6 to add a private authority for QPGMR of *USE. If this is not done, the start-up program receives an authority error trying to use that particular command for which *USE authority is needed.

After completing the editing, press F3 to exit the edit mode. The Enter key must be pressed again to exit the edit member function to take you back to the list of members. If there are any syntax errors, you are notified as you try to exit the edit session.

Debug/Validation Strategy for the Start-Up Program

If changes are made to the startup program, consider how to validate that the changes work correctly. What can be done to validate the startup program depends on the changes made to the program and if some particular function is performed by the program that must be done only at certain times. For example, if the program calls other programs to perform functions that can be done only during controlling subsystem startup, that will necessarily constrain the program is validated.

The IBM release versions of the startup program safely permit you to interactively call the startup program on a command line because there is a MONMSG command following each command that could reasonably be expected to fail if the startup program had already been run and the system was fully operational. This type of test is a valid first test of a changed program. That test does not catch authority errors caused by running the program under the QPGMR profile as during an actual startup. The obvious way to simulate that is to submit a job that runs under the QPGMR profile and calls the startup program.

To limit your exposure to problems with the startup program when more complex changes have been made, consider taking the system down to restricted state and restarting the controlling subsystem via the STRSBS command. Plan to do that when you are around to check if any problems occurred during execution of the startup program so you can deal with those problems. After you are confident that the startup program will operate correctly, schedule an IPL using the new program when no one is around to check for problems and deal with recovery.

Additional Editing Tips

Deleting Lines
Delete a single line by blanking it out and pressing the Enter key, or you can type D in one of the line number characters and press the Enter key to complete the delete. The redisplay shows the absence of the line. To delete a range of lines, type DD in the line number portion of the first line and last line of the set of lines to be deleted, and press the Enter key.

Copying Lines
Copy a single line by typing C in the line number portion of the line, type B to indicate insert before or type A to indicate insert after in the line number portion of another line, and press the Enter key to complete the copy. To copy a range of lines, type CC in the line number portion of the first line and last line of the set of lines to be copied, type B or A to indicate where the lines are copied, and press the Enter key.

Moving Lines
Move a single line by typing M in the line number portion of the line, type B to indicate insert before or type A to indicate insert after in the line number portion of another line, and press the Enter key to complete the move. To move a range of lines, type MM in the line number portion of the first line and last line of the set of lines to be moved, type B or A to indicate where the lines are moved, and press the Enter key.

Compiling the Modified Source

Type 14 as the OPT value to recompile the program. When you do this, press F4 (rather than the Enter key). Make sure the new name of the compiled program and library are correct. If you do not change the name and library from its previous name and library, you must change the Replace program parameter to *YES. If you do not, the new executable object is not put in the library where the previous version resides. Making simple changes as indicated above should cause no problems and the syntax checking was already performed as you did the editing and exited the edit session. Consequently, the compile should be clean and error free. You can check the compiler output spooled file to ensure that the compile was clean. You can also check the creation date/time of the executable program object to validate that the object was replaced by the compile.

If you compile a version of the QSTRUP program that is different from the version released with that release of the operating system, strongly consider changing the library of the newly compiled program to QGPL or some other user type library rather than leaving it as QSYS. (Remember to change the system value QSTRUPPGM if you do want the system to use a different version of the startup program.) For safety, keep the original released version in QSYS library under its original name. This could be used as a backup startup program if your new one becomes damaged or is somehow deleted. When a new version of the operating system is slip installed on a system, the QSTRUP program in QSYS will be the version provided by the new release. If your current startup program is in QGPL or some other user type library, it will not be automatically replaced by a new release version.