Create Partition Link
The Create Partition Link operation creates a new partition link object with the given properties.
HTTP method and URI
POST /api/partition-links
Request body contents
The request body is expected to contain a JSON object with the following fields:
Field name | Type | Rqd/Opt | Description | Supported "type" values |
---|---|---|---|---|
name | String (1-64) | Required | The value to be set as the partition link's name property. | All |
description | String (0-200) | Optional | The value to be set as the partition link's description
property. Default: an empty string |
All |
type | String Enum | Required | The value to be set as the partition link's type property. | All |
cpc-uri | String/ URI | Required | The value to be set as the partition link's cpc-uri property. | All |
bus-connections | Array of new-bus-connection objects | Optional | The value to be set as the partition link's bus-connections property. | smc-d, hipersockets |
starting-fid | Integer | Optional | The value to be set as the partition link's starting-fid
property. Default: 4096 |
smc-d |
starting-device-number | String (4) | Optional | The value to be set as the partition link's starting-device-number
property. Default: 7400 |
hipersockets |
maximum-transmission-unit-size | Integer | Optional | The value to be set as the partition link's
maximum-transmission-unit-size property. Only valid for the link type "hipersockets".
Default: 8 |
hipersockets |
partitions | Array of String/ URI | Required if type is "ctc" | A list of canonical URIs representing Partition objects to be added to the partition link. | ctc |
paths | Array of added-ctc-path-info objects | Required if type is "ctc" | An array of one or more paths represented by added-ctc-path-info nested objects where each element defines a new physical path that is to be used for communicating between provided partitions. | ctc |
devices-per-path | Integer (1-16) | Optional | Specifies the number of devices to be created per path on each partition
provided in the request. Constraint: devices is an optional field. If provided, the number of device numbers provided in device-numbers field must always be equal to the devices-per-path count. Default: 4 |
ctc |
Each nested new-bus-connection object contains the following fields:
Name | Type | Rqd/Opt | Description | Supported "type" values |
---|---|---|---|---|
partition-uri | String/ URI | Required | The canonical URI of the Partition object to be attached to the partition link. | smc-d, hipersockets |
number-of-nics | Integer | Required | Specifies how many NICs should be created. Additional details such as device
numbers or FIDs of the newly created NICs can be specified with the nics field.
|
smc-d, hipersockets |
nics | Array of new-nic objects | Optional | An array of NICs to be added to the specified partition connecting to the
newly created partition link. Constraint: The length of the array must be less than or equal to the value of the number-of-nics field. |
smc-d, hipersockets |
Each nested new-nic object contains the following fields:
Name | Type | Rqd/Opt | Description | Supported "type" values |
---|---|---|---|---|
device-numbers | Array of String (4) | Optional | The value to be set as the NIC's device-numbers property. Each device number is a string in the form of a 4-digit hexadecimal number. If the type of the partition link is "hipersockets", a set of up to 3 consecutive device numbers can be specified and the allowed value range is from 0000-FFFF. If the type of the partition link is "smc-d", only one device number is allowed and the value range is from 0001-FFFF. Default: auto-generated. Constraint: If the type of the partition link is "smc-d", this number must be unique across the device numbers of all other NIC elements of type roce or cna and all instances of the objects listed in PCI-based device numbers associated with the partition. If the type is "hipersockets", the number(s) must be unique across the device numbers of all other partition links of type "hipersockets" and all instances of object listed in Channel-based device numbers of the partition |
smc-d, hipersockets |
fid | Integer | Optional | The value to be set as the NIC's fid property. Constraints:
Default: auto-generated |
smc-d |
vlan-id | Integer (1-4094) | Optional | The VLAN ID associated with this NIC. This value can only be set when the type of the link is "hipersockets". | hipersockets |
mac-address | String | Optional | The MNAC address associated with this NIC. It must be unique among all the
NICs created in the CPC. The MAC address is represented as six groups of two lower-case hexadecimal
digits separated by colons (:). Only locally administered unicast MAC addresses are value, for
example, "02:ff:12:34:56:78". This value can only be set when the type of the link is
"hipersockets". Default: auto-generated |
hipersockets |
Each nested added-ctc-path-info object contains the following fields:
Name | Type | Rqd/Opt | Description | Supported "type" values |
---|---|---|---|---|
starting-device-number | String (4) | Optional | The value to be set as the path's starting-device-number property. The
starting-device-number is a string in the form of a 4-digit hexadecimal number. The allowed
value range is from 0000-FFFF. If not provided, the value will be automatically generated. The default value is 4000. |
ctc |
devices | Array of ctc-endpoint objects | Optional | Each element specifies the devices owned by all associated partitions in the
partition link. An array of ctc-endpoint objects, each ctc-endpoint has a pair of
endpoints between two partitions to form a valid communication path. Adding a new path:
Constraint: devices is an optional field. If provided, the number of device numbers provided in the device-numbers field must always be equal to the devices-per-path count. |
ctc |
adapter-port-uri | String/ URI | Required | Canonical URI path of the FICON Adapter object that represents the adapter port of the path. | ctc |
connecting-adapter-port-uri | String/ URI | Required | Canonical URI path of the FICON Adapter object that represents the connecting adapter port of the path. | ctc |
Each nested ctc-endpoint object contains the following fields:
Name | Type | Rqd/Opt | Description | Supported "type" values |
---|---|---|---|---|
endpoint-pair | Array of ctc-partition-devices-endpoint objects | Required |
Each element of the array specifies the device numbers to be used in creating ctc devices for a partition associated with the Partition link. Constraints:
|
ctc |
Each nested ctc-partition-devices-endpoint object contains the following fields:
Name | Type | Rqd/Opt | Description | Supported "type" values |
---|---|---|---|---|
device-numbers | Array of String (4) | Required | Each device number in the device-numbers property is a string in the
form of a 4-digit hexadecimal number. The allowed value range is from
0000=FFFF. Constraints:
|
ctc |
partition-uri | String/ URI | Required | The canonical URI representing a partition to be added to the partition link. | ctc |
Response body contents
On successful completion, the response body is a JSON object with the following fields:
Field name | Type | Description |
---|---|---|
job-uri | String/ URI | URI that may be queried to retrieve status updates of the asynchronous operation on the Partition link. |
Asynchronous result description
Once the operation has completed, a job-completion notification is sent and results are available
for the asynchronous portion of this operation. These results are retrieved using the Query
Job Status
operation directed at the job URI provided in the response body.
The result document returned by the Query Job Status operation is specified in the description for Query Job Status. When the status of the job is "complete", the results include a job completion status code and reason code (fields job-status-code and job-reason-code) which are set as indicated in Job status and reason codes. When this operation is successful, the job-results field contains an object with the following fields:
Field Name | Type | Description |
---|---|---|
operation-results | Array of attach-operation-status objects | Array of object in which each object represents the attachment status of a partition specified in the request body. |
Each nested attach-operation-status object contains the following fields:
Field Name | Type | Description |
---|---|---|
partition-uri |
String/ URI | The canonical URI path of the Partition object that is being added or removed. |
operation-status |
String Enum | The status of the asynchronous attach operation:
|
When it is not successful, the job-results field contains an object with the following fields:
Field Name | Type | Description |
---|---|---|
message |
String | The message text describing the detailed error that occurred when the operation was not successful. |
Description
This operation creates a partition link on the CPC identified by the cpc-uri field with the values specified in the request body. Any fields identified as required must be included in the request body. Any fields identified as optional may be excluded from the request body; if an optional field is not found in the request body, its value will be set to its default value. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered.
When the request body is valid, a 202 (Accepted) status code is sent as soon as the new partition link object has been created, but before the partitions are attached to it. The attachment of the individual partitions and the activation of the associated devices in each partition is performed asynchronously. The response has a Location header that provides the URI of the created partition link and the response body contains a URI that may be queried to retrieve the status of the asynchronous part of the operation. See Query Job Status for information on how to query the job status. The operation always triggers an asynchronous job even if the request does not contain any partitions to be attached.
The newly created partition link stays in "updating" state until all requested partitions have been successfully attached to the partition link. If the attach operation for any partition fails due to an error, the partition link will stay in "updating" state and the failed operations will be retried after an SE reboot. If the retry for a partition is not successful, this partition will be removed from the partition link and a hardware message on the owning CPC is created. The asynchronous job completes after all partition attachments have either succeeded or failed once. The job-results property contains further details on the outcome of the individual attachments.
If the API user does not have action/task permission to the Create Partition Link task, a 403 (Forbidden) status code is returned. A 404 (Not Found) status code is returned if the cpc-uri or any of the partition-uri fields do not designate a CPC or respectively a Partition object for which the API user has object-access permission. If the designated CPC is not in DPM mode, does not support the feature needed for the partition link type specified in the type field of the request, or is not in a valid state, 409(Conflict) status code is returned. A 409 (Conflict) status code is also returned if limits of the CPC or the partition are exceeded or values in the request body conflict with existing ones.
SMC-D and HiperSockets Partition Links
The connections between the partitions of the newly created partition link are described by the elements in the bus-connections array of the request body. Each entry in the bus-connections array must refer to an existing partition and define a set of NICs to be created. The NICs can be specified implicitly by providing only the number-of-nics field or optionally with additional details as part of the nics array. If the FID or device numbers are not specified for a SMC-D NIC, they will be automatically generated. The value of the starting-fid field will be used as the starting point for searching available FID numbers. If the device numbers or MAC address are not specific for a Hipersockets NIC, they will be automatically generated. The value of the starting-device-number field will be used as the starting point for searching available device numbers.
CTC Partition Links
The connections between the partitions are represented with in paths defined in the request. Each entry in the paths array represents a new CTC path to be defined through which the connections are formed between the partitions provided in the request. A valid CTC path can be defined by providing adapter-port-uri and connecting-adapter-port-uri representing FICON adapters enabled in CTC mode.
The defined path will be known as switched if both the provided adapters are connected to same switch, switched-loopback if both the provided adapters are representing same FICON Adapter, and point-to-point if both the provided adapters are connected to each other.
Each path can optionally have devices array representing the devices to be created on each partition provided in the request. Each entry in the devices array represent an endpoint-pair. It is optional to provide endpoint-pair in the request. If provided the number of endpoint-pair entries must be less than or equal to the total number of combinations possible between the partitions provided in partitions field in the request. Example: If 4 partitions are provided in partitions field, the number of endpoint-pairs entries must be 6. Partitions = {A,B,C,D},endpoint pairs = {(A,B),(A,C),(A,D),(B,C),(B,D),(C,D)}. Each entry in the endpoint-pair array represents a combination of partitions in a pair along with the devices represented by device-numbers to be created on each partition represented by partition-uri. The number of devices to be provided in the device-numbers must be equal to devices-per-path provided in the request. The endpoint-pair array must always have 2 entries representing a connection between a partition pair. If endpoint-pair entries are not provided in the request, the device numbers will be automatically generated for the partitions. The value of the starting-device-number field will be used as the starting point for searching available device numbers. The starting-device-number is automatically generated if not provided in the request.
Authorization requirements
This operation has the following authorization requirement:
- Object-access permission to the CPC whose object-uri is cpc-uri.
- Object-access permission to all Partition objects designated by a partition-uri field.
- Object-access permission to all FICON adapter objects designated by adapter-port-uri and connecting-adapter-port-uri fields.
- Action/task permission to the Create Partition Link 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 the 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. |
4 |
For partition links of type "hipersockets":
For partition links of type "ctc":
|
|
8 | The value of a field does not provide a unique value for the corresponding data
model property as required. The partition link name provided by the user is already in use by another partition link associated with the hosting CPC. For partition links of type "ctc":
|
|
15 | The request body contains a field whose presence or value is inconsistent with
the presence or value of another field in the request body. A prerequisite condition or dependency
among request body fields is not met. For partition links of type "ctc":
|
|
452 | For partition links of type "smc-d":
For partition links of type "hipersockets":
For partition links of type "ctc":
The error-details field of the response body contains a conflicting-device-numbers object (as described in Table 8) listing the device number values that are not unique. |
|
455 | For partition links of type "smc-d":
|
|
456 | For partition links of type "ctc", the provided combination of adapter-uris in paths does not form a valid path. | |
458 | For partition links of type "ctc", one of the adapters provided in the paths is not configured in FICON CTC mode. | |
459 | For partition links of type "ctc", the paths property must have at least one path defined to create the partition link. | |
460 | For partition links of type "hipersockets", the provided macs of any of the NICs is already in use on the hosting CPC. The error-details field of the response body contains an invalid-mac-details object listing the MAC values that are not unique. | |
462 | For partition links of type "ctc", the FICON adapter URI provided to define a path is already used by another path defined in the request. | |
403 (Forbidden) | 1 | API user does not have the required action/task permissions. |
404 (Not Found) | 2 | A URI in the request body does not designate an existing resource of the expected type or designates a resource for which the user does not have object-access permission. The error-details field of the response body contains an not-found-details object defined in Table 14, which identifies the objects that could not be found. |
409 (Conflict) | 5 | The CPC identified by the cpc-uri field is not enabled for DPM. |
6 | The operation cannot be performed because the state of the CPC hosting the partition link is not valid to perform the operation. It must be in one of the following states: "active", "service-required", "degraded", and "exceptions". | |
13 |
For partition links of type "smc-d":
|
|
329 | The operation cannot be performed because the CPC identified by the cpc-uri field is an unmanaged CPC, which is not supported by this operation. | |
427 | The CPC identified by the cpc-uri already has the maximum number of ISM or HiperSockets adapters defined. | |
550 | For partition links of type "smc-d", the CPC identified by the cpc-uri already has the maximum number of FIDs defined. | |
551 | Unable to generate new device numbers as there are not enough free device numbers available. | |
552 |
For partition links of type "smc-d":
|
|
553 |
For partition links of type "smc-d":
|
|
554 | The maximum number of allowed partitions for a partition link has been reached. | |
556 |
For partition links of type "smc-d":
|
|
557 | For partition links of type "hipersockets", the operation failed because
it requires the generation of one or more MAC addresses, the but range of available addresses has
been exhausted. [Added by feature dpm-hipersockets-partition-link-management] |
|
558 | For partition links of type "ctc", the number of devices defined in the
partition for a path has exceeded the limit of 256. [Added by feature dpm-ctc-partition-link-management] |
|
561 | For partition links of type "hipersockets", the maximum number of HiperSockets devices
that may be created for the CPC has been exceeded. [Added by feature dpm-hipersockets-partition-link-management] |
|
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. |
The conflicting-device-numbers object contains the following fields:
Field Name | Type | Description |
---|---|---|
conflicting-device-numbers | Array of conflicting-device-info objects | List of all the conflicting devices associated with the partition object |
The conflicting-device-info object contains the following fields:
Field Name | Type | Description |
---|---|---|
partition-uri | String/ URI | The URI of the partition corresponding to the conflicting device numbers. |
device-numbers | Array of String | Array of conflicting device numbers of the partition. |
The invalid-fid-details object contains the following fields:
Field Name | Type | Description |
---|---|---|
fids | Array of Integer | An array of FIDs that are invalid. |
The invalid-path-error object contains the following fields:
Field Name | Type | Description |
---|---|---|
paths | Array of adapter-uris objects | The value of this field contains all the paths that are invalid. |
The adapter-uris object contains the following fields:
Field Name | Type | Description |
---|---|---|
adapter-port-uri | String/ URI | The canonical URI of the source adapter of the path. |
connecting-adapter-port-uri | String/ URI | The canonical URI of the target adapter of the path. |
The invalid-mac-details object contains the following fields:
Field Name | Type | Description |
---|---|---|
macs | Array of String | The value of this field contains all the MACs that are invalid. |
The not-found-details object contains the following fields:
Field Name | Type | Description |
---|---|---|
object-uris | Array of String/ URI | The list of URIs of objects (partition, partition links) that are not found. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Job status and reason codes
HTTP error status code | Reason code | Description |
---|---|---|
200 (OK) | N/A | The Asynchronous attach operation is completed. The detailed status of the operation is available in the job-results field in the response |
500 (Server Error) | 100 | The job failed due to an internal error. The message text describes the error reason. |
101 | Partition link asynchronous attach job timed out. | |
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. |