Create Hipersocket
The Create Hipersocket operation creates and configures a HiperSockets adapter (type is "hipersockets"). For a CPC with API feature dpm-hipersockets-partition-link-management available, this operation should not be used to create an adapter of type "hipersockets", because such adapters are managed via Partition Links. Therefore, creating such an adapter should be done by sending a corresponding request to the Create Partition Link operation. [Updated by feature dpm-hipersockets-partition-link-management]
HTTP method and URI
POST /api/cpcs/{cpc-id}/adaptersRequest body contents
The request body is expected to contain a JSON object with the following fields:
| Field name | Type | Rqd/Opt | Description |
|---|---|---|---|
| name | String (1-64) | Required | The value to be set as the adapter's name property. The name value must be unique among all other adapters owned by the targeted CPC. |
| description | String (0-1024) | Optional | The value to be set as the adapter's description property. Default value: An empty string. |
| port-description | String (0-1024) | Optional | The value to be set as the description property
of the HiperSocket's single network-port. Default value: An empty string. |
| maximum-transmission-unit-size | Integer Enum | Optional | The value to be set as the adapter's maximum-transmission-unit-size property. Default value: 8 |
Response body contents
On successful completion, the response body contains a JSON object with the following fields:
| Field name | Type | Description |
|---|---|---|
| object-uri | String/ URI | The object-uri of the newly created Adapter object. |
Description
This operation creates and configures a HiperSocket with the values specified on the identified CPC and then returns its object-uri in the response body. The response also includes a Location header that provides this URI. An Inventory Change notification is emitted asynchronously to this operation.
If the API user does not have action/task permission to Create HiperSockets Adapter task, a 403 (Forbidden) status code is returned. If the object-id {cpc-id} does not identify a CPC object to which the API user has object-access permission, a 404 (Not Found) status code is returned. If the CPC identified by {cpc-id} already contains an adapter with the specified name, a 400 (Bad Request) status code is returned. If the CPC identified by {cpc-id} is not enabled for DPM, a 409 (Conflict) status code is returned. If the CPC identified by {cpc-id} already contains the number of HiperSockets identified by its maximum-hipersockets property, a 409 (Conflict) status code is returned.
If the request body fails to validate, a 400 (Bad Request) status code is returned. This may occur because the document defines a field that is not supported for the given adapter type.
If the request body contents are valid, the HiperSocket is created and its properties are configured to their corresponding request body content's field's values. If a field is not found in the request body, its property's value will be defaulted.
Authorization requirements
- Action/task permission to the Create HiperSockets Adapter task.
- Object-access permission to the CPC whose object ID is {cpc-id}.
HTTP status and reason codes
On success, HTTP status code 201 (Created) 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. |
| 8 | An adapter with the name specified in the request body already exists. | |
| 403 (Forbidden) | 1 | The API user does not have the action/task permission to the Create HiperSockets Adapter task. |
| 404 (Not Found) | 1 | A CPC with object ID {cpc-id} does not exist on the HMC or the API user does not have object-access permission for it. |
| 4 | The adapter does not support the operation, because its parent CPC is not enabled for DPM. | |
| 409 (Conflict) | 5 | A CPC with object ID {cpc-id} is 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. | |
| 427 | A CPC with object ID {cpc-id} already has the maximum number of HiperSockets adapters (identified by its maximum-hipersockets property) defined. | |
| 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
POST /api/cpcs/87dbe268-0b43-362f-9f80-c79923cc4a29/adapters
x-api-session: 3mwtrej0fkbg719l3jr5tvxyl2fd6h35que4x8jrukcl7l1802
content-type: application/json
content-length: 59
{
"name":"hiper1",
"description":"My hipersocket adapter"
}201 Created
"server":"zSeries management console API web server / 2.0",
"cache-control":"no-cache",
"date":"Wed, 10 Feb 2016 19:41:57 GMT",
"location":"/api/adapters/542b9406-d033-11e5-9f39-020000000338",
"content-type":"application/json;charset=UTF-8",
"content-length":"67",
{
"object-uri":"/api/adapters/542b9406-d033-11e5-9f39-020000000338"
}