Create Virtual Function

The Create Virtual Function operation creates a virtual function for the partition with the given identifier.

HTTP method and URI

POST /api/partitions/{partition-id}/virtual-functions

In this request, the URI variable {partition-id} is the object ID of the target Partition object.

Request 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 virtual function's name property.
description String (0-1024) Optional The value to be set as the virtual function's description property.
adapter-uri String/ URI Required The URI of the physical Accelerator adapter which will back the new virtual function.
device-number String Optional The value to be set as the virtual function's device-number property.

Response body contents

On successful completion, the response body contains a JSON object with the following fields:

Field name Type Description
element-uri String/ URI The element-uri property of the created virtual function object.

Description

This operation creates a virtual function for the identified partition and then returns the URI of the created object. Upon success, the response includes a Location header that provides the URI of the created virtual function object. An Inventory Change notification is emitted asynchronously to this operation.

If this operation changes the value of any property for which property-change notifications are due, those notifications are issued asynchronously to this operation.

A 404 (Not Found) status code is returned if the request URI does not designate an existing partition or designates a partition for which the API user does not have object-access permission. If the API user doesn't have action/task permission to the Partition Details task 403 (Forbidden) status code is returned. If the partition is in one of the transitional states ("starting" or "stopping"), or if the CPC is not in a valid state, a 409 (Conflict) status code is returned.

Authorization requirements

This operation has the following authorization requirements:
  • Object-access permission to the Partition object designated by {partition-id}.
  • Object-access permission to the Accelerator adapter designated by the request body.
  • Action/task permission to the Partition Details task.

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.

Table 1. Create Virtual Function: 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.
8 The virtual function name provided by the user is already in use by another virtual function of the partition, or the provided device-number is already in use by another Virtual Function element or by a NIC element of type "roce" of the partition.
403 (Forbidden) 1 The API user does not have the required permission for this operation.
404 (Not Found) 1 The request URI does not designate an existing resource of the expected type, or designates a resource for which the API user does not have object-access permission.
2 The adapter-uri in the request body does not designate an existing resource of the expected type, or designates a resource for which the API user does not have object-access permission.
409 (Conflict) 1 Partition status is not valid to perform the operation.
2 Partition object with ID {partition-id} was busy and request timed out.
6 The state of the CPC hosting the partition is not valid to perform the operation (must be in one of the following states: "active", "service-required", "degraded", or "exceptions".)
10 The operation cannot be performed because the affected SE is in the process of being shut down.
116 The partition does not have sufficient resources to perform this operation.
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. Create Virtual Function: Request
POST /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions HTTP/1.1
x-api-session: 63ba4ynuscmvljkablyprvm2ajhr67pa9b9jon5fz4k5jlt7gw
content-type: application/json
content-length: 101
{
   "adapter-uri":"/api/adapters/f36bf9ec-974f-11e5-bfaa-020000000192",
   "name":"New Virtual Function"
}
Figure 2. Create Virtual Function: Response
201 Created
server: zSeries management console API web server / 2.0
location: /api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions/621c6430-
   97e6-11e5-9e1e-020000000192
cache-control: no-cache
date: Tue, 01 Dec 2015 04:45:49 GMT
content-type: application/json;charset=UTF-8
content-length: 124
{
   "element-uri":"/api/partitions/b4c4bf9e-97e0-11e5-9d1f-020000000192/virtual-functions/
     621c6430-97e6-11e5-9e1e-020000000192"
}