IPL Directory Statement

Purpose

The IPL statement designates a named saved system or the device number of a device that CP automatically loads (IPLs) when the user logs on the virtual machine.

How to Specify

The IPL statement is allowed in profile, user, identity, and subconfiguration entries. An IPL statement in a user or identity entry overrides one in a profile entry. An IPL statement in a subconfiguration entry overrides one in an identity entry.

If you specify the IPL statement, it must precede any device statements in a directory entry. (For a list of device statements, see Table 1.)

Operands

vdev

is the virtual device number of the device CP is to automatically IPL when the user logs on. The variable vdev is any hexadecimal number from X'0000' to X'FFFF'.

nssname

is the 1- to 8-character alphanumeric name of a named saved system.

fcp_vdev

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

PARM parm_string

specifies a parameter string to pass to the user's virtual machine in general-purpose registers at the completion of the IPL. When you specify PARM, all characters that follow the statement are considered part of the parameter string. Therefore, you must code the PARM option last on the IPL statement. Although the IPL command allows for 64 bytes of parameters, the string on the directory statement is limited to the number of characters that can be specified in the first 71 positions of the statement. The string begins with the first nonblank character in the statement. (This differs from the IPL command, where trailing blanks are included.)

If you specify an IPL statement using a virtual device number, the parameter string is inserted into the virtual machine registers, 4 bytes per register, starting with register 0. One byte of binary 0's is inserted after the string. If PARM is specified without a parameter string (only blanks), byte 0 of register 0 contains binary 0's. If you omit PARM, the virtual machine's registers remain unchanged.

If you specify an IPL statement using a named saved system that was defined with the PARMREGS=m-n operand of the CP DEFSYS command, the parameter string is inserted into the virtual machine registers m through n that are first initialized to binary 0's. For more information on the CP DEFSYS command, see z/VM: CP Commands and Utilities Reference If you enter a string larger than can fit in the designated registers, an error message is issued during LOGON and the IPL command is rejected. If you omit PARM or specify it with no parameter string, the virtual machine registers contain all 0's.

If you specify an IPL statement using a named saved system that was defined with the PARMREG=NONE operand on the CP DEFSYS command, any parameter string causes an error message to be issued and the command to be rejected.

If you specify an IPL statement using a named saved system that was defined without the PARMREGS=m-n operand on the CP DEFSYS command, the parameter string is inserted into virtual machine registers 0 through 15. The registers are not initialized first to binary 0's. If you omit PARM or specify it with no parameter string, the virtual machine's registers remain unchanged.

LOADParm load_parm

specifies a 1- to 8-character load parameter that is used by the IPL'd system. It may be necessary to enclose the load parameter in single quotes. The load parameter may be retrieved by the guest operating system during its IPL sequence. It is preserved until a system-reset-clear operation is performed on the virtual machine; this operation resets it to 8 EBCDIC blanks.

Usage Notes

1. Although the CP IPL command allows up to 64 characters on the PARM option, the directory restricts each statement to a single card image. This restriction limits the number of characters that you can enter on the IPL statement in the directory.
2. If a user IPLs a named saved system that was created with the VMGROUP option on the CP DEFSYS command, that user's virtual machine becomes a member of the virtual machine group known by the NSS name. Members of a virtual machine group can connect to the signal system service to provide signalling within the group, including awareness messages (signal-in and signal-out) about members joining the group or leaving it.
3. A user whose virtual machine is a member of a virtual machine group and has the appropriate privilege class may authorize trace data recording to a system data file for the group.
4. For more information on the IPL command (including information about the LOADPARM and PARM options), see z/VM: CP Commands and Utilities Reference
5. The IPL action may not be completed if the user does not have certain privilege classes. For example, if IPL CMS is coded in a nonclass G virtual machine definition, the IPL fails because CMS issues class G CP commands using DIAGNOSE code X'08'.
6. Specifying the load parameter in single quotation marks gives you leading blanks, embedded blanks, or single quotation marks. Remember that any single quotation mark that is a part of the load parameter must be doubled. For example, use 'BETSY''S' to specify BETSY'S as a load parameter.
7. You may specify both the LOADPARM and PARM options when IPLing by either vdev or nssname. The PARM option must be the last option on the IPL statement.