IBM Changing the IPL Start-Up Program - V5R3M0 and Above - Unit...

1 of 4

https://www-304.ibm.com/support/docview.wss?uid=nas8N1019476

Changing the IPL Start-Up Program - V5R3M0 and Above

Technote (troubleshooting)
Problem(Abstract)
This document provides general information about the Start-Up program and detailed information on how to change it
for releases V5R3M0, V5R4M0, and V6R1M0

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.

27-Apr-15 3:45 PM

IBM Changing the IPL Start-Up Program - V5R3M0 and Above - Unit...

2 of 4

https://www-304.ibm.com/support/docview.wss?uid=nas8N1019476

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) COPYRIGHT0025.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 *NE0038.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
MONMSG
STRSBS
MONMSG

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

Starting TCP/IP

27-Apr-15 3:45 PM

IBM Changing the IPL Start-Up Program - V5R3M0 and Above - Unit...

3 of 4

https://www-304.ibm.com/support/docview.wss?uid=nas8N1019476

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 only if the system is a very generic, non-complex
system. Systems with tape libraries, Network Server Descriptions (NWSDs), custom subsystems that are responsible for
TCP applications, and so on should not use the IPL Attributes. 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

27-Apr-15 3:45 PM

IBM Changing the IPL Start-Up Program - V5R3M0 and Above - Unit...

4 of 4

https://www-304.ibm.com/support/docview.wss?uid=nas8N1019476

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.

Historical Number
23064116

Document
information
More support for:
IBM i
General
Software version:
5.4.0, 5.4.5, 6.1, 6.1.0,
6.1.1, 7.1, 7.1.0
Operating system(s):
IBM i
Reference #:
N1019476
Modified date:
2013-03-29

27-Apr-15 3:45 PM