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.
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
- 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]