SCSI Dump

The SCSI Dump operation loads a standalone dump program from a designated SCSI device. This operation is supported using the BCPii interface.

HTTP method and URI

POST /api/logical-partitions/{logical-partition-id}/operations/scsi-dump

In this request, the URI variable {logical-partition-id} is the object ID of the target Logical Partition object.

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
load-address String (1-5) Required The hexadecimal address of an I/O device that provides access to the control program to be loaded. The input value is right justified and padded with zeros to 5 characters.

Valid values are in the range "00000" to "nFFFF" where "n" is the number of subchannel sets provided by the CPC minus 1. So, for example, on a CPC that provides 3 subchannel sets, the valid range is "00000" to "2FFFF".

load-parameter String (0-8) Optional Some control programs support the use of this property to provide additional control over the outcome of a Load operation. Refer to the configuration documentation for the control program to be loaded to see if this parameter is supported and if so, what values and format is supported. Valid characters are 0-9, A-Z, blank and period. Three additional characters, (@, $, #) are also allowed when the se-version property of the associated CPC is "2.14.0" or later.
secure-boot Boolean Optional If true, the software signature of what is loaded will be checked against what the distributor signed it with. The load will fail if the signatures do not match. The default value is false.

This field is allowed only when the SE version is 2.15.0 with the suitable MCL bundle, or a later SE version.

world-wide-port-name String (1-16) Required The worldwide port name (WWPN) of the target SCSI device to be used for this operation, in hexadecimal.
logical-unit-number String (1-16) Required The hexadecimal logical unit number (LUN) to be used for the SCSI Dump.
disk-partition-id Integer (0-30) Optional The disk-partition-id (also called the boot program selector) to be used for the SCSI Dump. The default value is 0.
operating-system-specific-load-parameters String (0-256) Optional The operating system specific load parameters to be used for the SCSI Dump. The default value is an empty string.
boot-record-logical-block-address String (1-16) Optional The hexadecimal boot record logical block address to be used for the SCSI Dump. The default value is hex zeros.
force Boolean Optional Whether this operation is permitted when the logical partition is in "operating" status (true) or not (false).

Default: false

os-ipl-token String (1-16) Optional Applicable only to z/OS®, this parameter requests that this operation only be performed if the provided value matches the current value of the os-ipl-token property. This ensures that this operation is targeting the same IPL instance as when the os-ipl-token property was retrieved. IBM® recommends that this parameter only be provided by callers that fully understand how the os-ipl-token parameter is managed by z/OS. The value is a string of hexadecimal characters (0-9, A-Z), left justified.

Response body contents

Once the operation is accepted, the response body contains a JSON object with the following fields:

Field name Type Description
job-uri String/ URI URI that may be queried to retrieve status updates.

Asynchronous result description

Once the operation has completed, a job-completion notification is sent and results are available for the asynchronous portion of this operation. These results are retrieved using the Query Job Status operation directed at the job URI provided in the response body.

The result document returned by the Query Job Status operation is specified in the description for the Query Job Status operation. When the status of the job is "complete", the results include a job completion status code and reason code (fields job-status-code and job-reason-code) which are set as indicated in Job status and reason codes. The job-results field is null when this operation is successful. When it is partially successful or not successful, the job-results field contains an object with the following field:
Field name Type Description
message String The message text describing the detailed error that occurred when the operation was partially successful or not successful.

Description

When the operation is initiated, a 202 (Accepted) status code is returned. The response body includes a URI that may be queried to retrieve the status of the operation. See Query Job Status for information on how to query job status. When the operation has completed, an asynchronous result message is sent. See Job status and reason codes.

Authorization requirements

This operation has the following authorization requirements:
  • For the web services interface:
    • Object-access permission to the Logical Partition object designated by {logical-partition-id}
    • Action/task permission for the Load task.
  • For the BCPii interface the source partition must have receive BCPii security controls permissions for the Logical Partition object designated by {logical-partition-id}.

HTTP status and reason codes

On success, HTTP status code 202 (Accepted) is returned and the response body is provided as described in Response body contents.

The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.

HTTP error status code Reason code Description
400 (Bad Request) Various Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes.
403 (Forbidden) 0 The request used the BCPii interface and the source partition does not have receive BCPii security controls permission for the Logical Partition object.
404 (Not Found) 1 The object ID in the URI ({logical-partition-id}) does not designate an existing Logical Partition object, or the API user does not have object-access permission to the object.
500 (Server Error) 280 An IO exception occurred during the scheduling of the asynchronous request.

Additional standard status and reason codes can be returned, as described in Invoking API operations.

Job status and reason codes

HTTP error status code Reason code Description
204 (No Content) N/A Operation completed successfully.
500 (Server Error) 263 Operation failed.

Usage note

Beginning with API version 4.10 this operation will not be enhanced to support new load functionality. Instead, API users are encouraged to use Load, which includes the functionality of this operation as well as additional capabilities. [Updated by feature secure-boot-with-certificates]