Dump Partition

The Dump Partition operation loads a standalone dump program from a designated SCSI device. This operation is not supported when the "dpm-storage-management" feature is enabled on the target Partition object.

HTTP method and URI

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

In this request, the URI variable {partition-id} is the object ID of the target 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
dump-load-hba-uri String/ URI Required The URI of the HBA associated with the partition that provides access to the storage-area network containing the SCSI device from which the dump program is loaded.
dump-world-wide-port-name String (16) Required The worldwide port name (WWPN) of the target storage controller that contains the SCSI device from which the dump program is loaded, in hexadecimal.
dump-logical-unit-number String (1-16) Required The hexadecimal logical unit number (LUN) that identifies the SCSI device from which the dump program is loaded.
dump-configuration-selector Integer (0-30) Optional Selects the boot configuration to use from among multiple such boot configurations that have been defined by the operating system dump program to be loaded. Whether and how this parameter is used to determine boot parameters depends on the dump program and its boot process.

Default: 0, which indicates that the dump program's default boot configuration should be used.

dump-os-specific-parameters String Optional Specifies parameters that are passed unmodified to the loaded operating system dump program as part of the boot process. The way in which these parameters are used depends on the dump program, but in general, these parameters are intended to specify boot-time configuration settings.

Default: an empty string.

dump-record-lba String (1-16) Optional Specifies the logical block number of the anchor point for locating the operating system dump program on the SCSI disk from which the dump program is loaded. The way in which this parameter is used to locate the operating system depends on the operating system and its boot process.

Default: 0, identifying the first block on the device.

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 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 not successful.

Description

This operation loads a standalone dump program into the partition and begins its execution. It does so in such a way that the existing contents of the partition's memory are not overwritten so that the dump program can dump those contents.

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, with Job Status and Reason Codes described in Job status and reason codes.

A 404 (Not Found) status code is returned if the object ID {partition-id} does not identify a Partition object for which the API user has object-access permission or if the URI in the request body does not designate a resource of an expected type.

If the user does not have action/task permission to the Dump Partition task, a 403 (Forbidden) status code is returned. A 409 (Conflict) status code is returned if the partition's status is not valid to perform the operation. The valid partition states are "active", "degraded", "paused", or "terminated". A 409 (Conflict) is also returned when there is no storage controller at the WWPN specified, when the storage controller does not have a device with the specified LUN, or if the specified device does not contain a bootable dump program. If the partition has the "dpm-storage-management" feature enabled, a 409 (Conflict) status code is returned.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the partition.
  • Action/task permission for the Dump Partition task.

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.

Table 1. Dump Partition: HTTP status and reason codes
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) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The object ID in the URI ({partition-id}) does not designate an existing Partition object, or the API user does not have object-access permission to the object.
2 A URI in the request body does not designate a resource of an expected type
409 (Conflict) 12 The operation is not supported when the "dpm-storage-management" feature is enabled on the partition.
503 (Service Unavailable) 1 The request could not be processed because the HMC is not currently communicating with an SE needed to perform the requested operation.

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

Job status and reason codes

Table 2. Dump Partition: Job status and reason codes
HTTP error status code Reason code Description
200 (OK) N/A Operation completed successfully.
409 (Conflict) 1 Partition status is not valid to perform the operation (must be "active", "paused", or "terminated".
2 Partition object with ID {partition-id} was busy and request timed out.
6 The state of the CPC hosting the partition is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions".)
10 The operation cannot be performed because the affected SE is in the process of being shut down.
119 The specified device does not contain a bootable dump program.
500 (Server Error) 263 Operation failed.

Example HTTP interaction

Figure 1. Dump Partition: Request
POST /api/partitions/d28fc978-d535-11e5-804c-42f2e9cfe851/operations/scsi-dump HTTP/1.1
x-api-session: 12a74m6cfuaiiebwuceikrhaqq8bxx1a6kxl6xoihyyfel8x5d
content-type: application/json
content-length: 205
{
   "dump-load-hba-uri":"/api/partitions/d28fc978-d535-11e5-804c-42f2e9cfe851/hbas/bab7e3f8-
      d53a-11e5-a366-42f2e9cfe851",
   "dump-logical-unit-number":"00000",
   "dump-world-wide-port-name":"AFFCB01FF21BCAFA"
}
Figure 2. Dump Partition: Response
202 Accepted
server: zSeries management console API web server / 2.0
location: /api/jobs/ec9c31e8-d53b-11e5-a9b8-5ef3fcb21ee8
cache-control: no-cache
date: Wed, 17 Feb 2016 06:01:45 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
   "job-uri":"/api/jobs/ec9c31e8-d53b-11e5-a9b8-5ef3fcb21ee8"
}