Obtain a port

Use this operation to obtain a port from a resource pool that has a configured network resource pool.

HTTP method and URI path

POST /zosmf/resource-mgmt/rest/<version>/rdp/network/port/actions/obtain
In this request:
<version>
Is the URI path variable that identifies the version of the z/OSMF service. The following value is valid: 1.0.

Query parameters

None.

Description

This operation obtains a port from a resource pool with a configured network resource pool.

On successful completion, HTTP status code 200 (OK) is returned, indicating that the request resulted in a port being obtained.

Request content

The request content is expected to contain a JSON object that describes the port to be obtained. See Table 1.
Table 1. Request content for the obtain port request
Field name Type Required or optional Description
registry-uuid String See description Contains a unique identifier for the registry object that is associated with the resource pool. Derived from a workflow internal variable as follows:
  • Provisioning workflows: ${_workflow-registryID}
  • Action workflows: ${_workflow-parentRegistryID}

Required when provisioning network resources as part of a composite cluster template.

template-uuid String Optional This field is deprecated. It contains a unique identifier for the template that is associated with the resource pool. Derived from a workflow internal variable, ${_workflow-templateID}.
template-name String Required Name of the template that is associated with the resource pool. Derived from a workflow internal variable, ${_workflow-templateName}.
tenant-id String Required ID of the tenant that is associated with the resource pool. Derived from a workflow internal variable, ${_workflow-tenantID}.
network-parms JSON object Required Network parameters for the request. See Table 2.
Table 2. Network parameters fields
Field Type Required or optional Description
name String Optional Name used in a panel for the Network Configuration Assistant task to identify who is using the network resource. It is recommended to use workflow internal variable ${_workflow-softwareServiceInstanceName} for this parameter.
usage-type String Optional Used as a filter. If not specified, only network resource pools without a usage type match. If specified, must match the usage type in the network resource pool definition in the Network Configuration Assistant task.
port String Optional Request port number. If port is not specified, a port is provisioned from available port allocation ranges of the specified transport. If port is specified, it must fit within an available range. Available ranges are those which are associated with the targeted network resource pool and match the provided usage type.
job-name String Required Job name associated with the provisioned instance.
system-name String Optional System name. Derived from a workflow internal variable, ${_workflow-systemName}.
deployment-id String Optional Workflow-defined string token, used to group all provisioned resources with a server instance.
host-name String Optional Host-name for the Network Configuration Assistant task.
system-list[] String Optional A list of target systems for provisioning. If you omit this field and the system-name field, all systems in the network resource pool are targets. See Table 3.
is-port-shared String Optional Indicates whether the port should be capable of being shared with other servers on the same system that are listening on the same IP address and port. Used to enable same-system coexistence or when multiple equivalent servers normally run simultaneously on the same system bound to the same IP address and port.
is-port-distributed String Optional Indicates whether the port is used for workload distribution, as follows:
true
The port will be used in conjunction with provisioned distributed or group DVIPAs (IP addresses provisioned with a value of DYNAMIC for the recovery-method field) when creating the TCP/IP VIPADISTRIBUTE statement for workload distribution among the clustered instances. These are ports that the server application will use when binding its listening sockets to the distributed or group DVIPA.
false
The port is not used for workload distribution.
intent String Optional Indicates the intent, as follows:
shared
The port number can be reused for multiple port provisioning requests on the same TCP/IP stack. This is the default value.
exclusive
The port provisioning request is given a port number that has not been previously provisioned on this TCP/IP stack. Moreover, subsequent port provisioning requests do not return the same port number on the same TCP/IP stack, as long as this port remains provisioned.
workloadExclusive
The port provisioning request is given port numbers that are unique for each port provisioning request within the same cluster, regardless of the system or stack it is provisioned on.
Table 3. Systems field
Field Type Required or optional Description
sysplex-name String Required Name of the sysplex.
sysplex-node-name String Required Node name of the system.
system-nickname String Required Nickname of the system.

Authorization requirements

The user must be a consumer in the tenant, a domain administrator in the domain that the tenant is associated with, or a network administrator for APIs related to network resources in the domain that the tenant is associated with.

For more information, see Authorization requirements.

HTTP status codes

On successful completion, HTTP status code 200 (OK) is returned, with a response body. See Response content.

Otherwise, the following HTTP status codes are returned for the indicated errors. The response body is a standard error response body that provides the reason code that is indicated and associated error message.

Table 4. HTTP error response codes for an obtain port request
HTTP error status code Description
HTTP 403 The request cannot be processed because the client is not authorized.
HTTP 404 The requested resource does not exist.
HTTP 409 The request cannot be processed because of conflict in the request, such as an edit conflict between multiple updates.
HTTP 400 The request contained incorrect parameters.
HTTP 500 Internal server error The server encountered an error. See the response body for a JSON object with information about the error.

Response content

On successful completion, the service returns a response body, which contains a JSON object with details about the request. See Table 5.

Table 5. Response from an obtain port request
Field Type Description
id String Identifier of the port.
port String Port number.

Example HTTP interaction

In Figure 1, a request is submitted to obtain a port.
Figure 1. Sample request to obtain a port, with request body
POST https://localhost:4444/zosmf/resource-mgmt/rest/1.0/rdp/network/port/actions/obtain

{
"registry-uuid":"E1E2A1C4",
"template-uuid":"F0F1A1C2",
"template-name":"CICSBasic",
"tenant-id":"IZU$0AA",
"network-parms" :
{
"name":"PortForCics1",
"port":"80",
"usage-type":"Internal",
"job-name":"WLP001"
"deployment-id":"CICSBasic",
"host-name":"myHostName",
"is-port-shared":true,
"is-port-distributed":true,
"intent":"workloadExclusive",
"system-list": [
        {
                "sysplex-name" : "LOCAL",
                "sysplex-node-name" : "MVSW",
                "system-nickname" : "MVSWNIK"
        }
]
}
}

The following is the response body for the example obtain port request.

{
  "id":82346
  "port":"80",
 }