Add Temporary Capacity

The Add Temporary Capacity operation adds temporary processors or increases temporary model capacity to the CPC object designated by {cpc-id}. This operation is supported using the BCPii interface.

HTTP method and URI

POST /api/cpcs/{cpc-id}/operations/add-temp-capacity

In 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:

Field name Type Rqd/Opt Description
record-id String (1-8) Required Identifies the capacity record to be used for this request
software-model String (1-3) Optional The target software model. Implicit in the software model is the number of general purpose processors desired. When provided, this value must be one of the software models defined within the capacity record, and must represent a number of general purpose processors equal to or greater than the current software model. If the provided software model is equal to the current software model, or is not provided, the current software model is not changed.
processor-info Array of processor-info objects Optional A nested object that defines the number of specialty processors to be added. If not provided, the number of specialty processors is not changed.
force Boolean Optional Whether the operation proceeds if not enough processors are available (true) or not (false). The default is false.
test Boolean Required Whether the request should activate real or test resources for the capacity record. Set true if test or set to false if real. This is mainly used for Capacity Backup Upgrade (CBU) activations. See the Capacity on Demand User's Guide. For most records, field should be set to false.

processor-info object

Field name Type Rqd/Opt Description
processor-type String Enum Required Identifies the type of specialty processors to be affected. One of:
  • "aap" - Application Assist Processor
  • "ifl" - Integrated Facility for Linux® processor
  • "icf" - Internal Coupling Facility processor
  • "iip" - z Integrated Information Processors
  • "sap" - System Assist Processor
num-processor-steps Integer Optional The delta to the current number of processors. If not provided, the number of processors is not changed.

Description

Removal of these temporary resources can be performed manually through the Remove Temporary Capacity operation or automatically upon expiration of the capacity record.

Refer to the Capacity on Demand User's Guide for details on temporary capacity changes.

On success, HTTP status code 204 (No Content) is returned.

Authorization requirements

This operation has the following authorization requirements:
  • For the web services interface:
    • Object-access permission to the CPC object designated by {cpc-id}
    • Action/task permission for the Perform Model Conversion 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 204 (No Content) is returned and no response body is provided.

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.
271 A duplicate processor-type entry was found in the processor-info array, remove the duplicate entry.
275 The test value does not match the value stored in the capacity record.
276 Either the request specifies more resources than available or the requested software model specifies fewer resources than the current software model.
277 A temporary capacity record is already active. It must be deactivated before a new capacity record can be activated.
278 The software-model value was not found in the capacity record. Only software models as defined in the target capacity record can be specified.
298 The operation parameters conflict with the capacity record type:
  • force=true is permitted only for CBU, CPE and loaner capacity records.
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 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.
274 The requested capacity record does not exist.
409 (Conflict) 1 The operation is unavailable in the current CPC state:
  • The SE is not configured to allow temporary capacity changes through an API
  • The CPC status property is not "operating" or the CPC iml-mode property is not "lpar"
  • No physical processors are operating
  • The CPC is IMLed in a test or debug mode
  • An IML is required
2 The operation was rejected by the Support Element (SE), because the SE is currently performing processing that requires exclusive control of the SE. Retry the operation at a later time.
297 Some, but not all, of the requested resources were added.
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.
500 (Server Error) 275 An unexpected error occurred during the operation.
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.