Set zCPC Power Capping
Use the Set zCPC Power Capping operation to set the power capping settings of the zCPC portion of a CPC. This operation is supported using the BCPii interface.
HTTP method and URI
POST /api/cpcs/{cpc-id}/operations/set-zcpc-power-capping
In this request, the URI variable {cpc-id} is the object ID of the CPC.
Request body contents
The request body is a JSON object with the following fields:
Field name | Type | Rqd/Opt | Description |
---|---|---|---|
power-capping-state | String Enum | Required | The possible settings are:
|
power-cap-current | Integer | Optional |
Specifies the current cap value for the zCPC in watts (W). The current cap value indicates the power budget for the zCPC. This field is only required if the power-capping-state field is set to "enabled". The power-cap-current must be between zcpc-power-cap-minimum and zcpc-power-cap-maximum: zcpc-power-cap-minimum <= value <= zcpc-power-cap-maximum |
Response body contents
On successful completion, the response body is a JSON object with the following fields:
Field name | Type | Description |
---|---|---|
job-uri | String | URI of the asynchronous job that may be queried to retrieve status updates for action initiated by this operation. |
Description
Use this operation to limit the peak power consumption of a zCPC object designated by {cpc-id}, or to remove a power consumption limit for this object. You can closely manage power allocations within the physical limits of your data center.
This operation will always fail if the designated zCPC is under group control (see Group capping) or the zcpc-power-capping-state property of the zCPC is set to "not-supported" or "not-entitled". (See Energy management related additional properties for details on this property.) In addition, this operation is only available if feature code 0020 is installed on the system.
The action to change the power-capping settings occurs asynchronously. If the request is accepted, an asynchronous job is initiated and an HTTP Status code of 202 (Accepted) is returned. The response body includes a URI that may be queried to retrieve the status of the asynchronous job. See the description of the Query Job Status operation for information on how to query job status. When the asynchronous job has completed, an asynchronous result message is sent, with Job status and reason codes described below. After completion, the Query Job Status operation may be used to retrieve the completion results.
Authorization requirements
- For the web services interface:
- Object-access permission to all CPC and zCPC objects
- Action/task permission to the Power Capping task.
- For the BCPii interface, the source partition must have receive BCPii security controls permissions for the CPC object.
HTTP status and reason codes
On success, HTTP status code 202 (Accepted) is returned and the response body is provided as described inResponse body contents.
Otherwise, the following HTTP status codes are returned for the indicated errors. 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. |
7 | The power-cap-current field contains a value that is not in the range zcpc-power-cap-minimum ... zcpc-power-cap-maximum | |
5 | The power-cap-current field is not set, but power-capping-state field is set to "enabled". | |
403 (Forbidden) | 0 | The request used the BCPii interface and the source partition does not have receive BCPii security controls permission for the CPC object. |
1 | The user is not authorized to access the object or perform this task. | |
3 | The server is not entitled to perform energy management. | |
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) | 1 | The operation cannot be performed because the object designated by the request URI is not in the correct state. |
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. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Job status and reason codes
Job status codes | Job reason code | Description |
---|---|---|
200 (OK) | N/A | Operation executed successfully |
500 (Server Error) | 160 | A firmware error occurred while executing the operation |
161 | A hardware error occurred while performing the operation on the IBM zSystems hardware | |
162 | Communication error occurred while trying to access the IBM zSystems hardware |