Start Dump Program
The Start Dump Program operation loads a standalone dump program from a designated external location such as a storage disk.
HTTP method and URI
POST /api/partitions/{partition-id}/operations/start-dump-programIn 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-program-info | Object | Required | An object which identifies the location of the dump program and any additional parameters for loading or executing the dump program. The dump-program-type field indicates the type dump program and the type of object contained in this field. |
| dump-program-type | String Enum | Required | Indicates the type of dump program and identifies the type of object in
dump-program-info. Valid values:
|
The storage-volume-dump-program-info object contains the following fields:
| Field name | Type | Rqd/Opt | Description |
|---|---|---|---|
| storage-volume-uri | String/ URI | Required | Specifies the storage volume that shall be used to load the dump program. The value has to point to a valid URI of a fulfilled storage volume contained in a storage group attached to the partition. |
| dump-loader-mode | String Enum | Optional | Specifies the loader mode used when dumping from a FICON storage volume. Values:
The value must not be null when storage-volume-uri points to a FICON storage volume. The value can be set to either null or a valid value when storage-volume-uri points to a FCP or NVMe storage volume. If the value is not set when storage-volume-uri points to a FICON storage volume, the value is initialized automatically to "channel-command-word" if secure-boot is false or "list-directed" if secure-boot is true. [Added by feature secure-boot-with-certificates] |
| dump-record-location | boot-record-location object | Optional | Specifies the location of the boot record on the FICON storage volume. If the value is set to
null, the boot record location is derived from the volume label. The value can be set to either null or a valid value when storage-volume-uri points to a FCP or NVMe storage volume. Default: null Note: Not applicable if storage-volume-uri points to a FICON
storage volume and dump-loader-mode is "channel-command-word".
[Added by feature secure-boot-with-certificates] |
| dump-configuration | String Enum | Optional | Specifies how to determine the boot configuration used for booting the dump program.
Values:
Note: Not applicable if storage-volume-uri points to a FICON storage volume and
dump-loader-mode is "channel-command-word". If the value is not set, it is initialized
automatically to "automatic" if dump-configuration-selector is null or
"selector" if dump-configuration-selector is not null.
[Added by feature secure-boot-with-certificates] |
| 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. Note: Not applicable if storage-volume-uri points to a FICON storage volume and
"dump-loader-mode" is set to "channel-command-word".
[Updated by feature secure-boot-with-certificates] |
| secure-boot | Boolean | Optional | If true, the software signature of the dump program will be verified using the
certificate(s) assigned to the partition. Starting the dump program will fail if the signatures do
not match. Default: false [Added by feature secure-boot-with-certificates] |
| store-status | Boolean | Optional | If true, the dump stores the current values of the processing unit timer, the clock
comparator, the program status word, and the contents of the processor registers in their assigned
absolute storage locations. The value is only considered when storage-volume-uri points to a FICON storage volume, otherwise it is ignored. Default: false [Added by feature secure-boot-with-certificates] |
| dump-load-parameters | String (0-8) | 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. Not valid when storage-volume-uri points to a FICON® volume. Default : an empty string |
| dump-os-specific-parameters | String (0-256) | 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. Not valid when storage-volume-uri points to a FICON volume. Default : 0 (identifying the first block on the device) |
| timeout | Integer (60-600) | Optional | The time in seconds that is waited before the load of the dump program is aborted. Valid only when storage-volume-uri points to a FICON volume. Default: 60 |
Response body contents
Once the start request 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 not successful. |
Description
This operation loads a standalone dump program into the partition and begins its execution. It does so in a special 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 field in the "dump-program-info" does not designate a valid object to which the user has object-access permission.
If the user does not have authority to perform the Dump Partition action, 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".
If the partition does not have the "dpm-storage-management" feature enabled, a 409 (Conflict) status code is returned.
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.
| 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 operation is not supported when the "dpm-storage-management" feature is not enabled on the partition. |
| 2 | A URI in the request body does not designate a storage volume in a storage group attached to the partition. | |
| 409 (Conflict) | 13 |
The operation is not supported when the "dpm-storage-management" feature is not enabled on the partition. |
| 122 |
The operation cannot be performed because the "dump-program-info" contains a "storage-volume-uri" property that does not designate a storage volume that is fulfilled. |
|
| 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
| HTTP error status code | Reason code | Description |
|---|---|---|
| 200 (OK) | N/A | Start 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" and "exceptions".) | |
| 119 | The specified device does not contain a bootable dump program. | |
| 500 (Server Error) | 263 | Operation failed. |
Example HTTP interaction
POST /api/partitions/a5987806-9af5-11e8-86f5-00106f0ddbc9/operations/start-dump-program HTTP/1.1
x-api-session: 5o0m316dydfq37m0uo06mqyzg0bf06yq9t8qm4j80kyx18cnc
content-type: application/json
content-length: 222
{
"dump-program-info":{
"dump-load-parameters":"ABCD",
"storage-volume-uri":"/api/storage-groups/9e5d850c-9fc5-11e8-8c3e-00106f0ddbc9/
storage-volumes/9e765546-9fc5-11e8-8c3e-00106f0ddbc9"
},
"dump-program-type":"storage"
}202 Accepted
server: Hardware management console API web server / 2.0
location: /api/jobs/8cbf1be8-a057-11e8-a48e-00106f0d84e1
cache-control: no-cache
date: Wed, 15 Aug 2018 06:50:51 GMT
content-type: application/json;charset=UTF-8
content-length: 60
{
"job-uri":"/api/jobs/8cbf1be8-a057-11e8-a48e-00106f0d84e1"
}