SET DUMPDEV
- 1 A single invocation of the SET command sets no more than one value for any particular operand. Although you can specify a particular operand more than one time on a single invocation of the command, the command sets the value of only the last specification.
- 2 The letter 'h' in the syntax diagram represents a hex character in the range 0 - F. The number of letters indicates the maximum number of hex characters that can be entered (16). Leading zeros are not required.
Authorization
Privilege Class: G
Purpose
Use the SET DUMPDEV command to set parameters for a guest IPL with dump from a SCSI or ECKD disk. The parameters can identify the virtual device number and specify whether the IPL is a secure IPL. The parameters can identify the location of a system dumper program and information to pass to the program. The device that is IPLed is used to store the dump data.
- The IPL command specifies the fcp_vdev operand and the DUMP operand.
- The IPL command specifies the DUMPDEV operand.
The settings are temporary. The settings persist after an IPL but not after the user logs off. For more information, see IPL.
Operands
- CLEAR
-
The CLEAR operand clears all DUMPDEV parameters for all device types (SCSI and ECKD). Operands that follow the CLEAR operand are not cleared.
After DUMPDEV parameters are cleared, a guest IPL from SCSI or ECKD disk cannot be initiated until all required parameters for the SCSI or ECKD device type are set. The parameters that are required for each load device type are explained in usage note 1.
- SCSI
- The SCSI operand indicates that the DUMPDEV parameters are for IPL of a SCSI
device. Other operands on the command must be operands for a SCSI device.
If you do not specify the SCSI or ECKD operand, the device type defaults to SCSI.
After the SCSI parameter is set, subsequent SET DUMPDEV commands cannot set ECKD parameters until a SET DUMPDEV command with the CLEAR operand is specified. Likewise, DUMPDEV parameters for an ECKD device must be cleared before you can set DUMPDEV parameters for a SCSI device.
- ECKD
- The ECKD operand indicates that the DUMPDEV parameters are for IPL of an
ECKD device. Other operands on the command must be operands for an ECKD device.
Because SCSI is the default device type, the ECKD operand must be specified on every command that sets DUMPDEV parameters for an ECKD device.
After the ECKD parameter is set, subsequent SET DUMPDEV commands cannot set SCSI parameters until a CLEAR operand is specified. Likewise, DUMPDEV parameters for a SCSI device must be cleared before you can set DUMPDEV parameters for an ECKD device.
- DEVice fcp_vdev
- The DEVICE value
(fcp_vdev) specifies the virtual device number of the FCP device to IPL.
The combination of device number and port name must be unique from those specified in any ALTERNATE path definitions.
The DUMPDEV DEVICE parameter must be set before you can issue the IPL DUMPDEV command. A secure IPL with dump from a SCSI device can be initiated only by issuing the IPL DUMPDEV command.
If the IPL command specifies the fcp_vdev operand, then the DUMPDEV DEVICE parameter must match that value or must not be set.
- DEVice eckd_vdev
- The DEVICE value
(eckd_vdev) specifies the virtual device number of the ECKD device to IPL.
The DUMPDEV DEVICE parameter must be set before you can issue the IPL DUMPDEV command. A secure IPL with dump from an ECKD device can be initiated only by issuing the IPL DUMPDEV command.
- PORTname hhhhhhhh hhhhhhhh
- The PORTNAME value (hhhhhhhh hhhhhhhh) specifies the
8-byte fibre channel port name of the SCSI device that is
IPLed. The value must be a
hexadecimal value in the range 0 - FFFFFFFF FFFFFFFF. For values longer than eight hex characters,
at least one separator blank is required after the eighth character.
The combination of device number and port name must be unique from those specified in any ALTERNATE path definitions.
If you do not set the PORTNAME parameter, it defaults to 0.
- LUN hhhhhhhh hhhhhhhh
- The LUN value (hhhhhhhh hhhhhhhh) specifies the 8-byte
logical unit number of the SCSI device that is
IPLed. The value must be a
hexadecimal value in the range 0 - FFFFFFFF FFFFFFFF. For values longer than eight hex characters,
at least one separator blank is required after the eighth character.
If you do not set the LUN parameter, it defaults to 0.
- BOOTprog bootprog_number
- The bootprog_number value specifies the boot program that is loaded from the
SCSI or ECKD device that is IPLed. The value must be a decimal value in the
range 0 - 30.
If you do not set the BOOTPROG parameter, it defaults to 0.
- BOOTprog AUTOmatic
- The BOOTPROG AUTOMATIC operand loads the first system dumper program (not an
operating program) that is listed in the program table of the device that is IPLed.
If you do not set the BOOTPROG parameter, it defaults to 0.
- BR_LBA hhhhhhhh hhhhhhhh
- The BR_LBA value (hhhhhhhh hhhhhhhh) specifies the
logical-block address of the boot record of the SCSI device that is
IPLed. The value must be a
hexadecimal value in the range 0 - FFFFFFFF FFFFFFFF. For values longer than eight hex characters,
at least one separator blank is required after the eighth character.
If you do not set the BR_LBA parameter, it defaults to 0.
- BOOTREC cylinder head record
- The BOOTREC values (cylinder
head
record) specify the boot record location on the ECKD device that is IPLed. Use
hexadecimal values and separate the values by blank space. Leading zeros are not required. The
following ranges are allowed when you specify the boot record location:
- Cylinder: 0 - FFFFFFF
- Head (or track): 0 - F
- Record: 1 - FF
- BOOTREC LABEL
- The BOOTREC
LABEL operands specify that the boot record is the record that is identified in
the volume label of the ECKD device that is IPLed.
If you do not set the BOOTREC parameter, it defaults to LABEL.
- SECURE
- NOSECURE
- The SECURE operand
specifies that the IPL is a secure IPL.
The NOSECURE operand specifies that the IPL is not a secure IPL.
If you do not set the SECURE or NOSECURE parameter, the parameter defaults to NOSECURE.
The SECURE parameter is not valid unless the DEVICE parameter (virtual device number) is set.
Note: A secure IPL is required in the following situations:- If a user's OPTION directory statement includes the SECUREIPLREQUIRED option, a secure IPL is required.
- If the program to be dumped was IPLed with the SECURE parameter, then the DUMPDEV parameters must include the SECURE parameter.
- ALTERNATE
-
The ALTERNATE keyword specifies an alternate virtual device number and fibre channel port name to be IPLed if the initial device IPL fails. Up to three alternate paths can be set. A single invocation of the SET command can set no more than one alternate path. The combination of alternate device number and port name must be unique among all ALTERNATE definitions and different from the device number and port name combination that is specified by the DEVICE and PORTNAME keywords.
Alternate paths are used when the IPL is started by using the DUMPDEV operand (
IPL DUMPDEV
). Alternate paths are not used for list-directed IPLs that are started by specifying the virtual device number (IPL fcp_vdev). - SCPDATA ... text
- SCPDATA ... HEX hex_value
- The SCPDATA keyword designates data to be passed to the program that is
loaded for a list-directed IPL. If the program does not require any data, then the
SCPDATA parameter is optional.
The HEX keyword indicates that the data (hex_value) is UTF-8 encoded hex (characters 0-F). The hex string must be an even number of digits.
If the HEX keyword is not specified, the data is assumed to be EBCDIC text (code page 924). Quotation marks are necessary only if the text includes blanks, mixed case, is a valid keyword (NEW or APPEND), or is all numeric (a valid offset).
Up to 4096 (4K) characters of data (text or hexadecimal) can be entered. The actual number of input characters might be less than 4096 depending on the translation to UTF-8. Because two hex characters are required to represent each UTF-8 data byte, the maximum number of UTF-8 data bytes that can be defined by using the HEX option is 2048 (1/2 of the 4K character input limit).
There is no default value for SCPDATA.
- NEW
- The parameter value that follows the NEW keyword replaces any previously specified SCPDATA data.
- APPEND
- The parameter value that follows the APPEND keyword is appended to the end of any previously specified SCPDATA data.
- offset
- The offset value indicates an offset of the previously specified SCPDATA data. The parameter value that follows the offset value overlays the previously set SCPDATA data beginning at the specified offset. The offset value must be a value from 0 to the current length of the SCPDATA data.
Usage Notes
- DUMPDEV parameters are used for list-directed IPLs. Table 1 shows which DUMPDEV parameters have default values that must
be set (changed from the default) before each type of guest IPL with dump can be started. Other
parameters might need to be set if the default values are not appropriate for your environment.
Note that a list-directed IPL with dump uses DUMPDEV parameters. A list-directed IPL without dump uses LOADDEV parameters. See IPL and SET LOADDEV.
Table 1. DUMPDEV parameters requirements by type of guest IPL with dump IPL type DEVICE parameter PORTNAME parameter LUN parameter SECURE parameter IPL fcp_vdev DUMP The DEVICE parameter is not set or matches fcp_vdev on the IPL command Required Required The SECURE parameter is not allowed when the fcp_vdev operand is used IPL DUMPDEV from SCSI device Required Required Required Required if the previous IPL used the SECURE parameter or if the SECUREIPLREQ option is specified in the OPTION directory statement IPL DUMPDEV from ECKD device Required Not applicable Not applicable - To prepare for a secure IPL, the program that is loaded must be signed. The appropriate certificate must be loaded in the HMC and assigned to any LPAR on which the IPL might occur.
- DUMPDEV parameters can be set only by using the SET DUMPDEV command.
- The DUMPDEV settings of a user can be displayed by using the QUERY DUMPDEV command. See QUERY DUMPDEV.
- The initial SET DUMPDEV command or the first SET
DUMPDEV command after a SET DUMPDEV CLEAR command establishes the
device type (SCSI or ECKD) until another SET DUMPDEV CLEAR command is issued.
Until another SET DUMPDEV CLEAR is issued, SET DUMPDEV
commands with operands for a different device type are not valid. Because the default device type is
SCSI, when you set an ECKD load device you must specify the ECKD operand on every SET
DUMPDEV command issued. For example:
SET DUMPDEV CLEAR ECKD DEVICE 1234 SET DUMPDEV ECKD BOOTREC 0 0 5
- After a DUMPDEV parameter is set, it can be changed by issuing the SET
DUMPDEV command with a new value for the same parameter. It is not necessary to use the
CLEAR operand before you change a parameter value. There are two exceptions:
- The first exception is the device type parameter (SCSI or ECKD). You must use the CLEAR operand before you specify a new device type parameter.
- The second exception is for alternate device paths (SCSI). You can set up to three alternate device paths. When you want to change one or more of the currently set alternate paths, you must first use the CLEAR operand. The CLEAR operand clears all alternate paths. You can then set up to 3 alternate paths.
- The
z/VM® stand-alone dump utility does
not support list-directed IPL from ECKD, and does not support secure IPL from SCSI or ECKD.
Therefore, you cannot set the following DUMPDEV parameters to IPL z/VM stand-alone dump in a virtual machine:
- ECKD
- SECURE
- The default DUMPDEV value for the PORTNAME and LUN parameters is 0, which is not a valid device port name and not a valid device LUN. An IPL attempt that uses the default value for the PORTNAME or LUN parameter will fail.
- If the IPL of the initial device by using the IPL DUMPDEV command
is not successful and alternate paths are set, then the alternate device paths are automatically
considered:
- If a device is not available, then the next alternate path is considered.
- Alternate device paths are considered in turn until IPL is successful or all device paths are considered and IPL is not successful.
Examples
- The following command identifies port a20, logical unit number 03 as the SCSI device,
and passes the SCPDATA=x'74657374' to the system dumper program that is loaded during a guest IPL.
set dumpdev port a20 lun 03 scpdata hex 74657374
- After the command in the previous example completes, the following command replaces '57' in the
SCPDATA with '75'. The offset of 3 indicates where the data overlay begins. The resulting SCPDATA
value is 74675374.
set dumpdev scpdata 3 hex 75
Messages
- HCP002E Invalid operand - operand
- HCP021E A device number was not supplied or it is invalid.
- HCP1611E Limit of three ALTERNATE definitions exceeded.
- HCP1611E Device fcp_vdev PORTNAME hhhhhhhh hhhhhhhh is already part of the definition.
- HCP1613E An attempt was made to set both SCSI and ECKD parameters for a future IPL. These are conflicting parameters.
- HCP2768E Missing cylinder number
- HCP2768E Missing track number
- HCP2768E Missing record number
- HCP2813E CP is running on a processor that does not support guest secure IPL.
- HCP2813E One or more systems in your relocation domain do not support guest secure IPL.
- HCP2813E CP is running on a processor that does not support list-directed IPL from ECKD devices.
- HCP2813E One or more systems in your relocation domain do not support list-directed IPL from ECKD devices.
- HCP2813E CP is running on a processor that does not support BOOTPROG AUTOMATIC.
- HCP2813E One or more systems in your relocation domain do not support BOOTPROG AUTOMATIC.
- HCP2825E SCPDATA format conflicts with previous input
- HCP2826E SCPDATA contains invalid UTF-8 data: data
- HCP2827E SCPDATA offset exceeds current length of data (length)
- HCP2828E SCPDATA length exceeds maximum allowed (maximum)
- HCP2829E SCPDATA does not contain a valid hex string
- HCP6704E Missing token at end of line
- HCP6706E Invalid string - string
- HCP6706E Invalid number - number
- HCP6706E Invalid cylinder number - cylinder
- HCP6706E Invalid track number - track
- HCP6706E Invalid record number - record