SET DUMPDEV

Read syntax diagramSkip visual syntax diagram Set DUMPDEVCLEARCLEARSCSISCSI OperandsECKDECKD Operands
SCSI Operands
Read syntax diagramSkip visual syntax diagram1DEVicefcp_vdevPORTnamehhhhhhhh hhhhhhhh2LUNhhhhhhhh hhhhhhhh2BOOTprogbootprog_numberAUTOmaticBR_LBAhhhhhhhh hhhhhhhh2NOSECURESECUREALTernatefcp_vdevPORTnamehhhhhhhh hhhhhhhh2SCPdataAPPendNEWoffsettextHEXhex_value
ECKD Operands
Read syntax diagramSkip visual syntax diagram1DEViceeckd_vdevBOOTprogbootprog_numberAUTOmaticBOOTRECcylinderheadrecordLABELNOSECURESECURESCPdataAPPendNEWoffsettextHEXhex_value
Notes:
  • 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 parameters that are set by using the SET DUMPDEV command are called DUMPDEV parameters and are used only for list-directed IPLs, which occur in the following cases:
  • The IPL command specifies the fcp_vdev operand and the DUMP operand.
  • The IPL command specifies the DUMPDEV operand.
See usage note 1.

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.

Start of change The combination of device number and port name must be unique from those specified in any ALTERNATE path definitions.End of change

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.

Start of change The combination of device number and port name must be unique from those specified in any ALTERNATE path definitions.End of change

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. Start of changeThe 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.End of change

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

  1. 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.
    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
    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.
  2. 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.
  3. DUMPDEV parameters can be set only by using the SET DUMPDEV command.
  4. The DUMPDEV settings of a user can be displayed by using the QUERY DUMPDEV command. See QUERY DUMPDEV.
  5. 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
  6. 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.
  7. 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
    More information about IPLing the z/VM stand-alone dump utility is available. See The Stand-Alone Dump Utility in z/VM: CP Planning and Administration.
  8. 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.
  9. 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

  1. 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
  2. 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 Start of changePORTNAME hhhhhhhh hhhhhhhhEnd of change 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