Change Adapter Type

The Change Adapter Type operation reconfigures an adapter from one type to another. Currently, only storage adapters can be reconfigured. Storage adapter instances represent daughter cards on a physical storage card. Current storage cards require both daughter cards to be configured to the same protocol, so changing the configuration of the targeted adapter will also change the configuration of the adapter instance that represents the other daughter card on the same physical adapter. API clients that need to determine the related adapter instance can do so by finding the storage adapter card with a matching first 9 characters (card ID and slot ID) of their card-location property values.

HTTP method and URI

POST /api/adapters/{adapter-id}/operations/change-adapter-type

In this request, the URI variable {adapter-id} is the object ID of the Adapter object.

Request body contents

The request body is expected to contain a JSON object with the following fields:

Field name Type Rqd/Opt Description
type String Enum Required The value to be set as the adapter's type property. Values:
  • "fcp" - Fibre Channel attached storage resource.
  • "fc" - Fibre Connection attached storage.
  • "not-configured" - The adapter is not configured.

Description

This operation reconfigures a storage adapter to support a new storage protocol.

If the API user does not have action/task permission to the Configure Storage – System Programmer task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the object ID {adapter-id} does not identify an Adapter object on the HMC.

If the request body fails to validate, a 400 (Bad Request) status code is returned. This could be because the current value of the adapter's adapter-family property is not "ficon" or its detected-card-type property value is "ficon-express-32s". If the value of the adapter’s status property is "exceptions", or if the current value of the adapter's type property is already set to the value specified in the type field in the request body, of if the adapter is configured to any partition, or the adapter's current type is "fc" and it, or the adapter on the same physical card, is connected to a storage switch, a 409 (Conflict) status code is returned.

If the request body contents are valid, the adapter's type property and the type property of the adapter with the same card id and slot id, as identified by the first 9 characters of their card-location property values, are updated to the value specified in the type field in the request body. The two adapters are reconfigured to the new storage protocol.

Property change notifications for the type property of both affected adapters are emitted asynchronously to this operation.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the adapter whose object ID is {adapter-id}
  • Action/task permission to the Configure Storage – System Programmer task.

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.

Table 1. Change Adapter Type: HTTP status and reason codes
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.
18 The operation is not allowed for the adapter’s adapter-family or detected-card-type.
403 (Forbidden) 1 The API user does not have action/task permission to the Configure Storage – System Programmer task.
404 (Not Found) 1 An adapter with object ID {adapter-id} does not exist on the HMC.
4 The adapter does not support the operation, because its parent CPC is not enabled for DPM.
409 (Conflict) 1 Adapter status is not valid to perform the operation (does not allow the updating of a specified adapter property).
2 The adapter object with the object-id {adapter-id} was busy and the request timed out.
488 The adapter’s type property is already set to the value of the type field in the request body.
489 The adapter is configured to at least one partition.
496 The adapter with object ID {adapter-id}, or the adapter on the same physical card, has an endpoint connection to a storage switch.
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.

Example HTTP interaction

Figure 1. Change Adapter Type: Request
POST /api/adapters/e835bb78-9fe7-11e8-bc9a-fa163e3c2af4/operations/change-adapter-
  type HTTP/1.1
x-api-session: 2fypcb9w0z7kzv9rtq7yfxaypayrdh209nmrrdyv1jetvhxfu0
content-type: application/json
content-length: 15
{
   "type":"fcp"
}
Figure 2. Change Adapter Type: Response
204 No Content
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Wed, 15 Aug 2018 17:02:33 GMT

<No response body>