Stop CPC
The Stop CPC operation stops the CPC object designated by {cpc-id}. The target CPC object must be enabled for DPM.
HTTP method and URI
POST /api/cpcs/{cpc-id}/operations/stopIn this request, the URI variable {cpc-id} is the object ID of the target CPC object.
Request Body Contents
The request body is expected to contain a JSON object with the following fields. If none of the optional fields are included, an empty request body must be supplied.
| Field name | Type | Rqd/ Opt | Description |
|---|---|---|---|
| dual-control-request-information | dual-control-request-info object | Required if the operation requires dual control approval for the API user | A nested object containing information as described in Table 1 to be used to create a Dual-Control Request object that will be associated with this operation. [Added by feature dual-control] |
Response body contents
If the operation does not require dual control approval for the API user and 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 stop status updates. |
If the operation requires dual control approval for the API user and the dual control request is created, the response body contains a JSON object with the following field. See Dual control considerations for more information.
| Field name | Type | Description |
|---|---|---|
| dual-control-request-uri | String/ URI | The URI of the newly created Dual-Control Request object that represents the request. |
Asynchronous result description
If the operation does not require dual control approval for the API user and 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
Stop CPC is an orderly process for shutting down and turning off the CPC.
Shutting down and turning off the CPC, referred to also as stopping the CPC, includes:
- Ending hardware and software activity
- Clearing, releasing, and de-allocating hardware resources
- Turning off power.
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 seen in Job status and reason codes.
Dual control considerations
This operation may be subject to dual control approval before the action can be started. If the API user has a User Role that is configured to require dual control approval for the task and target combination in this operation, the request body must contain some dual control request information, the dual-control-request-information field. If that information is not included, status code 409 (Conflict) is returned. In addition, if that dual control request information is provided when it is not required, status code 409 (Conflict) is returned. Use the Get Dual Control Information operation to determine if this operation requires dual control approval for the API user.
When the operation requires dual control approval for the API user, a different HTTP status code and object are returned to indicate that the request is under dual control. When the operation is initiated, and dual control approval is required, a 201 (Created) status code is returned. The response body and a Location response header contain the URI of a new Dual-Control Request object that represents the requested action. All remaining interaction with the request, including obtaining its final status, is through that Dual-Control Request object. The dual-control-request-status-code and dual-control-request-reason-code fields of the Dual-Control Request's task-results object will contain the HTTP status code and reason code, respectively, for this operation.
Authorization requirements
- Object-access permission to the CPC object designated by {cpc-id}
- Action/task permission for the Stop task.
HTTP status and reason codes
On success, either HTTP status code 201 (Created) or 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 object ID in the URI ({cpc-id}) does not designate an existing CPC object, or the API user does not have object-access permission to the object. |
| 409 (Conflict) | 5 | The operation cannot be performed because the CPC object designated by {cpc-id} is currently not enabled for DPM. |
| 329 | The operation cannot be performed because the CPC designated by the request URI is an unmanaged CPC, which is not supported by this operation. | |
| 16 | The operation requires dual control approval but the required dual control information is not present in the request body. [Added by feature dual-control] | |
| 17 | The operation does not require dual control approval but the dual control information is present in the request body. [Added by feature dual-control] | |
| 500 (Server Error) | 280 | An IO exception occurred during the scheduling of the asynchronous request. |
| 503 (Service Unavailable) | 1 | The request could not be processed because the HMC is not communicating with the 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
| Job status code | Job reason code | Description |
|---|---|---|
| 204 (No Content) | N/A | Operation completed successfully. |
| 500 (Server Error) | 263 | Operation failed or was rejected due to the current CPC status. The CPC status is unknown. Refer to the message parameter in the error response body for details. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Usage note
This operation stops a CPC object that is enabled for DPM only. If the targeted CPC object is not enabled for DPM, the Deactivate CPC operation may be used instead. Refer to Deactivate CPC for details.