IPL

Device Operands

Parameters

FCP Operands

Notes:

¹ If the last IPL was successful, the invocation of IPL with no operands executes the last IPL specified. If an abbreviation is used for this invocation of IPL, error message HCP022E will be issued.

Authorization

Privilege Class: G

Purpose

Use IPL to simulate an initial program load function for your virtual machine.

Note: The IPL command is not supported for secondary processors.

Operands

system_name

is a named saved system that was previously saved with the SAVESYS command.

vdev

specifies the virtual device that you want to IPL.

Note: DASD which is defined as being unsupported cannot be IPLed by CP. Unsupported DASD can only be used by a virtual machine which is IPLed either from a supported device or from a named saved system.

fcp_vdev

If the specified virtual device is an FCP-attached device and the DUMP operand is not specified, a guest IPL from SCSI disk will be initiated. This feature requires that parameters have previously been defined with the SET LOADDEV command.

If the specified virtual device is an FCP-attached device and the DUMP operand is specified, a guest IPL from SCSI disk with dump will be initiated. This feature requires that parameters have previously been defined with the SET DUMPDEV command.

If the specified virtual device is an FCP-attached device and the NSSDATA operand is specified, then the DUMP operand must also be specified.

cylno

blkno

is the location of the IPL data when vdev specifies a DASD device. For CKD and ECKD DASD devices, this operand specifies the cylinder number which contains the IPL data. For FBA DASD devices, this operand specifies the starting block number where the IPL data is located. If not specified and the vdev identifies a DASD device, virtual cylinder 0 or block number 0 are defaulted. This operand is only for virtual direct access storage devices.

NOCLear

allows the contents of your virtual machine's storage to remain unchanged prior to program load. NOCLEAR is the default.

CLear

sets the contents of your virtual machine's storage to binary zeros before the operating system is loaded.

DUMP

causes a guest IPL from SCSI disk with dump to be initiated when specified with an FCP-attached virtual device. This feature requires that parameters have previously been defined with the SET DUMPDEV command.

The dump function is very similar to List-Directed IPL with three differences:

Prior to loading the machine loader into storage a model dependent amount of guest storage is saved in simulated HSA. The anchor and size of the storage area will be saved in the base VMDBK of the guest requesting the dump.
Instead of loading a system image from the SCSI device identified with a SET LOADDEV command, a system dumper is loaded from the SCSI device identified by SET DUMPDEV. The same device is also used to store the dump data. The format of LOADDEV and DUMPDEV are identical.
The system dumper calls DIAG X'308' with subcode 2 to release the data saved in simulated HSA.

NSSDATA

causes a private copy of the contents of the existing embedded NSS (named saved system) to be preserved in memory after the IPL command has completed.

If NSSDATA is specified when IPLing an FCP device, then the DUMP operand must also be specified.

Using the NSSDATA operand requires the following:

The NSS is fully contained within the first extent of guest memory
The NSS does not contain SW, SN or SC pages
The NSS is not a VMGROUP NSS.

If any of these requirements are not satisfied, the command fails and the system remains unchanged.

STOP

halts the virtual machine during the IPL procedure just after the initial PSW is loaded. This permits you to simulate an IPL procedure in instruction step mode for your virtual machine.

When your virtual machine stops, you can enter CP commands. To restart the virtual machine, enter the BEGIN command.

ATTN

sends an attention interrupt to your virtual machine during the IPL procedure.

LOADParm load_parm

specifies a 1- to 8-character load parameter. If fewer than eight characters are specified, the load parameter is left-justified and padded with blanks; it may be necessary to enclose the load parameter in single quotation marks (see Usage Note 11). If LOADPARM is not specified, a load parameter of eight EBCDIC blanks is formed.

The load parameter is converted to upper case and may include only the upper case alphabetic characters (A-Z), digits 0-9, the period, and the blank.

The load parameter may be retrieved by the guest operating system during its IPL sequence. Its use is determined by the guest operating system, such as indicating the nucleus to be loaded during the IPL sequence.

PARM

PARM parm_string

specifies a parameter string up to 64 bytes long to pass to your virtual machine in general purpose registers at completion of IPL. The parameter string begins with the first nonblank character following PARM. It consists of all remaining characters that follow on the command line, including trailing blanks. If you specify other optional parameters on the IPL command, you must enter PARM last.

If you are IPLing a device, the parameter string is inserted into the virtual machine registers, four bytes per register, starting with register 0. If the string is less than 64 bytes, a single byte of binary zeros is inserted following the string. If you enter PARM followed only by blanks, the byte of zeros is passed in the high-order byte of register 0. If you omit PARM, the virtual machine registers are unchanged. If you are IPLing an NSS that was defined with the PARMREGS=m-n option on the DEFSYS command, the parameter string is inserted into the virtual machine registers m through n, which are first initialized to binary zeros. For further information, refer to the DEFSYS command. If you enter a string too large to fit in the designated registers, an error message is issued, and the command is not processed. If you specify PARM followed by all blanks or if you omit PARM, the virtual machine registers specified by the PARMREGS option on the DEFSYS command contains all zeros.

If you are IPLing an NSS that was defined with the PARMREGS=NONE option on the DEFSYS command, specifying the PARM option results in an error message being issued and in the command not being processed.

If you are IPLing an NSS that was defined without the PARMREGS=m-n option on the DEFSYS command, the parameter string is inserted into the virtual machine registers 0 through 15. The registers are not first initialized to binary zeros. If you specify PARM followed by all blanks or if you omit PARM, the virtual machine registers are unchanged.

Usage Notes

When the IPL command is entered from the virtual machine console as the first or only command on a CP command line (that is, while TERMINAL MODE is CP, or CP READ is displayed or the command line begins with #CP), VM attempts to break out of certain wait conditions that might exist. Thus the IPL command may be entered to cause breakout of certain virtual machine wait conditions.
The breakout attempt occurs when the IPL command is entered, not when the command is processed. Command errors do not prevent the breakout attempt. In some cases a breakout resets the virtual machine.
If you want to use the AUTOCR, BATCH, NOSPROF, INSTSEG, or SAVESYS parameters of the IPL command, you must have PARMREGS=0-15 in the DEFSYS command for the CMS named saved system.
IPL simulates the LOAD operation on the real system console. The specified virtual device is accessed, and the required input/output operations are performed to retrieve the IPL data. This does not pertain to named saved systems.
Optionally, you can stop the IPL procedure after loading the virtual PSW. Also, you can pass parameters to the virtual machine's general registers. When the simulated load function is complete, CP initiates execution of the virtual machine by loading the IPL PSW, which was stored during the simulation process.
If you enter ipl system_name or ipl vdev clear, the IPL command performs a system-reset-clear function on your virtual machine as if the SYSTEM CLEAR command were processed. If you enter ipl vdev noclear or if you enter ipl vdev and NOCLEAR is taken as the default, the IPL command performs a system-reset-normal function on your virtual machine as if the SYSTEM RESET command were processed. The effects of a system-reset-normal or system-reset-clear function are described in detail in the description for the SYSTEM RESET and SYSTEM CLEAR commands.
Any logical lines following the IPL command are ignored because execution of the IPL command transfers control from the CP environment to the virtual machine environment.
The IPL sequence for the program that you want to IPL must use only format 0 CCWs.
After you enter the IPL command, the pseudo page fault facility is deactivated. To activate (or reactivate) the pseudo page fault facility, you must enter the SET PAGEX command with the ON operand. For more information, see Usage Note 2 in the description of the SET PAGEX command.
Care must be used when passing parameters to a named saved system (system_name). Named saved systems may expect certain registers to be initialized when they are given control. Indiscriminate use of the PARM operand could overlay a previously initialized register, causing unpredictable results.
When system_name is equal to a hexadecimal device number, the device is IPLed if it exists; otherwise, the named saved segment is IPLed.
If you do not want leading blanks or embedded blanks in the load parameter, you may specify the load parameter as a single blank-delimited token. Specifying the load parameter within single quotation marks enables you to specify leading blanks or embedded blanks.
The load parameter may not contain a X'15' character.
You may specify both the LOADPARM and PARM options when IPLing by either vdev or system_name. Both options may be specified on the same command line. However, if you specify the PARM option, it must be the last option on the command.
If you IPL an NSS that was created with the VMGROUP option on the DEFSYS command, your virtual machine becomes a member of the virtual machine group that is known by the NSS name. Members of a virtual machine group are permitted to connect to the signal system service and to provide intragroup signaling, including awareness messages (signal-in and signal-out) about members joining the group or leaving it.
If your machine is a member of a virtual machine group, a user with an appropriate privilege class may authorize trace data recording into a system data file for the group by issuing a TRSAVE command and specifying FOR sysname.
If the tape drive specified is in a Given State, the issuer must be the user ID to whom the tape drive was given, or the command will not be performed.
This command terminates all Concurrent Copy (CONCOPY) sessions for your virtual machine.
If the IPL command is entered without abbreviation, (that is, is entered as IPL rather than I or IP), the command is accepted without parameters. When IPL is entered without parameters, the system repeats the operation of the last successful IPL command entered, or responds with an error message if there was no previously successful IPL.
If an external security manager is installed on your system, you may not be authorized to enter this command. For additional information, contact your security administrator.
Processing of an IPL command on an NSS might be delayed if DIAGNOSE code X'64' is concurrently performing the initial load of a large DCSS.
The NSS name _0___1__ is reserved for IBM® use.
The IPL command will fail if issued when VMRELOCATE is in progress.
The contents of an NSS preserved by processing the NSSDATA parameter includes storage keys that are accurately preserved with the exception of the reference bit, which is unreliable. The change bit is always off for SR and ER pages of an NSS and they cannot be changed by the user. Therefore the change bit is never on for preserved SR or ER pages.
Immediately after an NSS is restored by the IPL command, the virtual machine's architecture mode is determined by its MACHINE setting, as follows:

ESA:

The same as it was when the NSS was saved (that is, ESA/390 or z/Architecture®), or ESA/390 if the NSS was saved while in ESA/XC mode

XC:

ESA/XC

Z:

z/Architecture

If the architecture mode on completion of the IPL command differs from that at SAVESYS, the PSW is converted to the appropriate format (that is, from a 64-bit ESA/390 or ESA/XC PSW to a 128-bit z/Architecture PSW, or vice versa).

Options

Optional CMS Initialization Parameters: The following CMS parameters are passed to the system profile EXEC (SYSPROF EXEC). Any unrecognized parameters are ignored by CMS initialization, but are still passed to the SYSPROF EXEC.

CMS users can use the PARM operand to specify any of the following CMS parameters:

AUTOCR

is the automatic carriage return parameter that simulates the pressing of the ENTER key as input to the virtual machine at the initial VM READ. Your PROFILE EXEC is automatically executed if it exists on your file mode A.

BATCH

indicates that the CMS IPL is being performed in a batch instead of an interactive virtual machine.

Use of this parameter does not affect execution of the SYSPROF EXEC. Execution of the SYSPROF EXEC is suppressed only if the NOSPROF parameter was specified.

At the beginning of each job, the batch facility work disk is accessed and immediately erased, preventing the current user job from accessing files that might remain from the previous job. Because of this, execution of the PROFILE EXEC is disabled for the CMS Batch Facility machine. However, if the BATPROF EXEC exists on an accessed system disk, it is invoked instead of the PROFILE EXEC.

FILEPOOL filepoolid

specifies the default file pool that is established as the user's file mode A. If FILEPOOL is not specified, 191 is established as the file mode A.

The following parameters are ignored by the SYSPROF EXEC, but processed by CMS initialization.

NOSPROF

indicates that the SYSPROF EXEC is bypassed. You must specify NOSPROF if you intend to enter the CMSBATCH command when the initial VM READ is issued. When the SYSPROF EXEC does not exist, you do not have to specify NOSPROF to enter the CMSBATCH command.

INSTSEG YES

links the default CMS installation saved segment for this CMS session. The CMS installation saved segment is an optional shared segment that contains EXECS and editor macros that your installation provides.

INSTSEG NO

indicates that you do not want to use the CMS installation saved segment during this CMS session.

INSTSEG name

links the named CMS installation saved segment for this CMS session. The segment may be a physical or a logical saved segment.

SAVESYS sysname

is used in the process of creating named systems. The SAVESYS parameter is available only to Class E users. It saves a virtual machine storage space with registers and PSW as they currently exist. The operand sysname must be a predefined name representing a definition of installation requirements of the named system. The definition indicates the number of pages to be saved, the DASD volume on which the system is to be saved, and the shared segments, if any.

After the system is saved, initialization continues, all CMS parameters entered on the IPL command are ignored, and SYSPROF EXEC is processed. The parameters entered on the original IPL command are not passed to SYSPROF EXEC.

No other parameters may be specified with this parameter. If any other parameters are specified, all parameters are ignored, and a CONFLICT parameter is passed to SYSPROF EXEC, as well as the parameters entered on the IPL command.

MTSEG YES

links the default CMS multitasking segment for this CMS session. The CMS multitasking segment is an optional shared segment that contains the CMS multitasking enablement code.

Note: The CMS multitasking segment is no longer used because the multitasking enablement code is now included in the CMS nucleus. This parameter has no effect and is retained only for compatibility.

MTSEG NO

indicates that you do not want to use the CMS multitasking segment during this CMS session.

Note: The CMS multitasking segment is no longer used because the multitasking enablement code is now included in the CMS nucleus. This parameter has no effect and is retained only for compatibility.

MTSEG name

links the named CMS multitasking segment for this CMS session. The segment may be a physical or a logical multitasking segment.

Note: The CMS multitasking segment is no longer used because the multitasking enablement code is now included in the CMS nucleus. This parameter has no effect and is retained only for compatibility.

Optional CMS Initialization Usage Notes

If you want to use the NOSPROF, INSTSEG, or SAVESYS parameters of the IPL command, you must have PARMREGS=0-15 specified on the DEFSYS command for the CMS named saved system.
To indicate that the CMS initial program load is being performed in a batch rather than an interactive virtual machine, you must specify either the BATCH parameter on the IPL command or the NOSPROF parameter, and then enter the CMSBATCH command at the VM READ. Then a BATPROF EXEC is processed in the batch machine, rather than a PROFILE EXEC. This option causes the CMS nucleus to issue the CMSBATCH command to load the batch processor. Specifying the BATCH option eliminates the need for operator intervention between jobs. See The CMS Batch Facility in z/VM: CMS Planning and Administration for information.
AUTOCR should not be used for AUTOLOG users if SET AUTOREAD OFF is in the user's profile.
Note: For a disconnected CMS service virtual machine, this mechanism can be useful. The name of a CMS restart routine can be specified in the CMS nucleus. In case of an abend, the specified restart routine receives control instead of the service virtual machine entering a disabled wait state. If this routine issues an IPL CMS PARM AUTOCR command, the PROFILE EXEC processes initial setup procedures that allow the service virtual machine to reestablish itself.
The SYSPROF EXEC contains some of the CMS initialization function. When you IPL CMS, it is executed by default before any file modes are accessed. The user PROFILE EXEC is invoked after the SYSPROF EXEC. You can bypass the SYSPROF EXEC by specifying the NOSPROF parameter on the IPL command.
If you have defined disks with virtual device numbers 190 and 19E in the system directory, or if they are defined before you IPL CMS, these disks are accessed as the S- and Y-disks, respectively. After you IPL CMS, you must enter explicit ACCESS commands to access other disks. Ordinarily, you have access only to files with a file mode number of 2 on the system disk.
If you have defined disk address 191 and the FILEPOOL parameter is omitted, the 191 disk is accessed as file mode A. However, if the FILEPOOL parameter is specified, your top directory in the identified file pool is accessed as file mode A, even if you also have a 191 minidisk defined. If the access of the top directory fails (perhaps because the file pool is unavailable), the 191 minidisk is accessed. If there is no 191 minidisk, nothing is accessed as file mode A.

When ACCESS is the first command issued after an IPL of the CMS system, file mode A is not automatically defined. Another ACCESS command must be issued to define file mode A.

For more information, see CMS ACCESS command in z/VM: CMS Commands and Utilities Reference.
If you have a disk defined as virtual device number 192, the following special rules apply when CMS is IPLed:
- If 192 is an unformatted temporary minidisk or virtual disk in storage, CMS formats it and accesses it as file mode D.
- If 192 is a CP-formatted temporary minidisk or virtual disk in storage, CMS reformats it for CMS use and accesses it as file mode D.
- If 192 is a CMS-formatted temporary minidisk, virtual disk in storage, or permanent minidisk that is accessed as a file mode other than D, CMS reaccesses it as file mode D.
- If 192 is an unformatted or CP-formatted permanent minidisk, CMS does not automatically format, reformat, access, or reaccess it.
When CMS accesses a 192 minidisk as file mode D, any minidisk or SFS directory already accessed as D is released.

Responses

Usually, after a successful IPL, any responses you receive are those from the operating system that was loaded and initialized.

Response 1:

Trace active at IPL

is issued when tracing is active.

Response 2:

IPL stop at xxxxxxxx

is issued after the IPL is complete when the STOP option is specified.

xxxxxxxx: is the address where execution of the loaded program starts.

After this response is issued, your virtual console is placed into CP READ so that you may enter CP commands (for example, TRACE). After entering all desired CP commands, issue the BEGIN command to start executing the loaded program.

Messages

Note: A guest IPL from SCSI disk might cause non-CP messages to be displayed that are not included here. For descriptions of these messages, see Start of change

IBM Z: Small Computer Systems Interface (SCSI) IPL Machine Loader Messages (SC28-7006) End of change

Messages:

HCP003E Invalid option - {option|command contains extra option(s) starting with option}
HCP006E Invalid device type - {rdev|vdev|ldev}
HCP013E Conflicting option - option
HCP014E Conflicting operands - operand1, operand2
HCP022E A virtual device number was not supplied or it was invalid.
HCP040E Device {rdev|vdev|ldev} does not exist
HCP044E System {name|volume} does not exist
HCP052E [XAUTOLOG failed for userid:] Error in CP directory
HCP053E [XAUTOLOG failed for userid:] userid|value not in CP directory
HCP059E {XAUTOLOG|AUTOLOG} failed for userid - {IPL missing|IPL failed|accounting errors|incorrect password}
HCP170E System name exceeds storage size; {nnnnnnnnK|nnnnM} required
HCP174E Paging I/O error; IPL failed
HCP175E IPL is not allowed on a secondary CPU; IPL failed
HCP177E Your PARM data exceeds the limit of nn characters. Correct your data string and reissue the IPL command.
HCP232E IPL UNIT ERROR, {CSW=csw|IRB=irb}, SNS=sense
HCP235E IPL with NSSDATA failed because the NSS {exceeds the end of the first extent of guest memory. | contains page range(s) of type SW, SC, or SN. | is defined with the VMGROUP attribute. | extends into unassigned increments.}
HCP236E The NSSDATA operand is not allowed with the IPL of an NSS.
HCP237E The NSSDATA operand must be specified after the DUMP keyword for the IPL of an FCP device.
HCP260E IPL command processing cannot complete due to errors.
HCP356E Access denied; User userid file spoolid not {changed|transferred|printed}
HCP410E CP ENTERED; PAGING ERROR
HCP447E System sysname cannot be IPLed due to an invalid processor configuration.
HCP449E Your userid is not authorized to IPL system name.
HCP475I Fatal I/O error trying to read directory from volid [for user userid]
HCP799E IPL failed due to insufficient or faulty storage
HCP819I Traceid traceid disabled; group group enabled by traceid
HCP838E The request process cannot complete due to a processor controller failure.
HCP1001E An operand is missing for option.
HCP1013E An invalid operand was supplied for option - operand
HCP1015E [XAUTOLOG failed for userid:] Insufficient storage is available to satisfy your request.
HCP1122E command was not performed. Tape vdev has been given to user userid.
HCP1352E System name cannot be processed.
HCP1600E Specified cylinder number cylinder is not on the virtual DASD.
HCP1601E The PARM option is not allowed for the system specified with the IPL command.
HCP2813E CP is running on a processor or in a mode that does not support IPL with DUMP to SCSI devices.
HCP2813E CP is running on a processor or in a mode that does not support IPL from SCSI devices.
HCP2815E The virtual storage size must be greater than nnnnM to IPL from a SCSI device.
HCP2816I Acquiring the machine loader from the processor controller.
HCP2817I Load completed from the processor controller. Now starting the machine loader.
HCP2818E The request to load the machine loader from the processor controller has been cancelled.
HCP2824E No {LOADDEV|DUMPDEV} parameters are currently defined
HCP6056I XAUTOLOG information for userid: The IPL command is verified by the IPL command processor.
HCP6061I APPC wait canceled; virtual machine has been reset.
HCP6086I Traceid traceid1 is no longer superseded by VMGROUP trace traceid2.
HCP6094I User userid will not be traced by trace traceid.
HCP6097I User userid has restricted tracing to traces defined as BLOCK.
HCP6525E Authorization request failed.