Fulfill FICON Storage Volume
The Fulfill FICON Storage Volume operation maps the ECKD storage resource that has been configured by a SAN administrator to a storage volume that is part of a request for new or modified FICON® storage.
HTTP method and URI
POST /api/storage-groups/{storage-group-id}/storage-volumes/{storage-volume-id}/operations/
fulfill-ficon-storage-volume
In this request, the URI variable {storage-group-id} is the object ID of the Storage Group object and the URI variable {storage-volume-id} is the element ID of the storage volume element.
Request body contents
Field name | Type | Rqd/Opt | Description |
---|---|---|---|
control-unit-uri | String/ URI | Required | The canonical URI of the storage control unit in which the backing ECKD volume is defined. |
unit-address | String (2) | Required | A two-character lower case hexadecimal number that represents the unit address of the backing ECKD volume within the storage control unit. |
Description
This operation provides information about the ECKD storage resource that has been selected by a SAN administrator to fulfill a base storage volume that is part of a request for new or modified FICON storage. Until this information is provided, the CPC does not have all the data it needs to address and connect to that storage resource.
Once a FICON storage volume has been fulfilled, the storage control unit and unit that has been assigned to it cannot be changed. If the size, cylinders or model properties of a volume are modified, the fulfillment-state of the volume is changed to "pending", indicating that action may be necessary by the storage administrator to adjust the size of the backing ECKD volume. The fulfillment-state of the volume is changed back to "complete" by fulfilling the volume again with the exact same control-unit-uri and unit-address, indicating that the changes have been completed.
If the API user does not have action/task permission to the Configure Storage – Storage Administrator task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID {storage-group-id} does not identify a storage group object to which the API user has object-access permission, or the element ID {storage-volume-id} does not identify a storage volume in the storage group, or the control-unit-uri in the request body does not identify a storage control unit, or the current value of the group’s type property is not "fc".
If the storage volume’s fulfillment-state property value is not "pending", or if the CPC on which this storage group resource exists is not active, or if the storage group's connectivity property value does not equal the number of storage paths configured in the target storage control unit, a 409 (Conflict) status code is returned. A 409 (Conflict) status code is also returned if the identified unit address is not defined on the identified control unit, or if the backing ECKD volume is an alias volume or has already being used to fulfill another storage volume, or if the identified control unit and unit address would remap a previously fulfilled storage volume, or if the backing ECKD volume is in a different CPC than the target storage volume.
If the request body fails to validate, a 400 (Bad Request) status code is returned.
If the request body contents are valid, the storage volume’s fulfillment-state property is changed to "complete". If the fulfillment-state property values for all other storage volumes in the parent storage group are also "complete", the parent storage group’s fulfillment-state property will also be set to "complete". The storage volume’s control-unit-uri and unit-address properties are set to the same-named request body field values. The storage volume’s size and model property values are copied to the active-size and active-model properties. Change notifications for the storage volume’s fulfillment-state, control-unit-uri, unit-address, active-size, and active-model properties are emitted asynchronously to this operation. Change notification for the parent storage group’s fulfillment-state property may be also emitted.
Authorization requirements
- Object-access permission to the storage group whose object-id is {storage-group-id}.
- Action/task permission to the Configure Storage – Storage Administrator task.
HTTP status and reason codes
On success, HTTP status code 204 (No Content) is returned and no response body is provided.
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. |
403 (Forbidden) | 1 | The API user does not have action/task permission to the Configure Storage – Storage Administrator task. |
404 (Not Found) | 1 | A storage group with the object-id {storage-group-id} does not exist on the HMC or the API user does not have object-access permission for it. |
2 | The storage control unit identified by control-unit-uri does not exist on the HMC. | |
4 | The storage group object with the object-id {storage-group-id} has a type value other than "fc". | |
5 | A storage volume with element-id {storage-volume-id} does not exist in the storage group on the HMC. | |
409 (Conflict) | 1 | The state of the CPC is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions"). |
2 | The storage group object with the object-id {storage-group-id} was busy and the request timed out. | |
441 | The storage control unit reference by the control-unit-uri field resides in a different CPC than the targeted storage volume. | |
471 | The current value of the fulfillment-state property of the storage volume identified by {storage-volume-id} is not "pending". | |
473 | The storage volume identified by {storage-volume-id} has been previously fulfilled, and the values of the control-unit-uri and unit-address fields do not exactly match the previous values. | |
484 | The unit address identified by unit-address is not a member of a volume group on the control unit identified by control-unit-uri. | |
485 | The unit address identified by unit-address in the control unit identified by control-unit-uri has already been used to fulfill another FICON storage volume. | |
486 | The unit address identified by unit-address is a member of an alias volume group on the control unit identified by control-unit-uri. | |
492 | The connectivity property value of the storage volume identified by {storage-volume-id} does not equal the number of storage paths configured in the storage control unit identified by control-unit-uri. | |
503 (Service Unavailable | 1 | The request could not be processed because the HMC is not currently 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.