Create Partition Link

The Create Partition Link operation creates a new partition link object with the given properties.

POST /api/partition-links

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
smc-d/hipersockets: Nested object properties

Each nested new-bus-connection object contains the following fields:

Each nested new-nic object contains the following fields:

ctc: Nested object properties

Each nested added-ctc-path-info object contains the following fields:

Each nested ctc-endpoint object contains the following fields:

Each nested ctc-partition-devices-endpoint object contains the following fields:

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:

Each nested attach-operation-status object contains the following fields:

When it is not successful, the job-results field contains an object with the following fields:

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.

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.

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.

The conflicting-device-numbers object contains the following fields:

The conflicting-device-info object contains the following fields:

The invalid-fid-details object contains the following fields:

The invalid-path-error object contains the following fields:

The adapter-uris object contains the following fields:

The invalid-mac-details object contains the following fields:

The not-found-details object contains the following fields:

Additional standard status and reason codes can be returned, as described in Invoking API operations.