Using dynamic port allocation in a template

You can specify that a template uses dynamic port allocation, and control which range of ports are used for dynamic allocation by setting a usage type. You can use this to provision a CICS® region that obtains dynamically allocated ports from different port ranges, depending on the use of the requested port.

About this task

When you add a CICS template by using IBM® Cloud Provisioning and Management for z/OS®, you can use the z/OSMF ability to allocate ports dynamically from port ranges. Typically, a network administrator uses z/OSMF to define a range of ports for use with templates and supplies this information to the system administrator who creates the templates.

By default, when a container is provisioned, any available port is allocated from the port allocation ranges that were defined for use with a template.

However, you can control which range of ports are used for dynamic allocation by setting a usage type. Typically, the network administrator uses z/OSMF to set a usage type when they define each port allocation range for use with templates. When you use z/OS PT to create a template, you use a configuration property to specify the required usage type for a type of port. When a container that requires such a port is provisioned, any available port is allocated from the port allocation range that this usage type identifies.

z/OS PT supports the following configuration properties for port usage types.

DFH_JVM_DEBUG_USAGETYPE. Sets the usage type for the port that a Java™ debugger can be connected to.
DFH_REGION_CMCIPORT_USAGETYPE. Sets the usage type for a CMCI port (used for connection to CICS Explorer®).
DFH_REGION_HTTP_USAGETYPE. Sets the usage type for an HTTP port.
DFH_REGION_HTTPS_USAGETYPE. Sets the usage type for an HTTPS port.
DFH_REGION_IPIC_USAGETYPE. Sets the usage type for an IPIC port.
DFH_REGION_TCPIP_USAGETYPE. Sets the usage type for the CICSPlex® SM WUI port.

You can use specific port ranges for different purposes, for example, you might use different port ranges for different categories of CICS applications.

You can use several approaches to use specific port ranges for different purposes:

Create a number of templates, where each one is configured for a different usage type. Remember that with this approach, each template requires a setup and approval process.
Create a template that is configured for multiple usage types, then configure and build different images for the different usage types.
Create a template that is configured for one or more usage types. Either configure and build different images for the different usage types, or configure and build different images that override the usage type. You need to specify that the relevant usage type configuration properties can be overridden in an image. See Modifying the set of CICS configuration properties that can be overridden.

The following procedure outlines how to use specific port ranges for different purposes by creating a template that is configured for multiple usage types.

Procedure

Use z/OSMF to create the required port allocation ranges and set a usage type for each range.
In z/OSMF, Usage Type is an optional field, but you must set it here so that you can use it in the template configuration. You would usually set a unique usage type for each port allocation range. Typically, a network administrator completes this step. For more information, see Create a port allocation range in z/OSMF Online Help.
Use z/OS PT to create a new template, as described in Adding a CICS template by using IBM Cloud Provisioning and Management for z/OS.
1. When you configure the cics.properties file, add one or more of the following configuration properties and specify the usage type for each one. The usage type name must match the Usage Type field set in z/OSMF for the port allocation range that you require.
  - DFH_JVM_DEBUG_USAGETYPE. Sets the usage type for the port that a Java debugger can be connected to.
  - DFH_REGION_CMCIPORT_USAGETYPE. Sets the usage type for a CMCI port (used for connection to CICS Explorer).
  - DFH_REGION_HTTP_USAGETYPE. Sets the usage type for an HTTP port.
  - DFH_REGION_HTTPS_USAGETYPE. Sets the usage type for an HTTPS port.
  - DFH_REGION_IPIC_USAGETYPE. Sets the usage type for an IPIC port.
  - DFH_REGION_TCPIP_USAGETYPE. Sets the usage type for the CICSPlex SM WUI port.
  A valid usage type name is 1-32 characters and the following valid characters: A-Z a-z 0-9
  For example:
```
# Set networking variables
DFH_REGION_HTTP=YES
DFH_REGION_HTTP_USAGETYPE=http

DFH_REGION_HTTPS=YES
DFH_REGION_HTTPS_USAGETYPE=https

DFH_JVM_DEBUG=YES
DFH_JVM_DEBUG_USAGETYPE=jvm

DFH_REGION_TCPIP=YES
DFH_REGION_TCPIP_USAGETYPE=WUIport

DFH_REGION_CMCIPORT_USAGETYPE=CMCIport

DFH_REGION_IPIC=YES
DFH_REGION_IPIC_USAGETYPE=ipic
```
When you use the z/OSMF web interface to add the template to z/OSMF and associate the template with a tenant in the domain, a network resource pool is generated.
Use the Network Configuration Assistant in z/OSMF to modify the network resource pool to specify the port allocation ranges that are associated with the tenant and the template.
Typically, a network administrator completes this step. For more information, see Modify the network resource pool in z/OSMF Online Help.
Use z/OS PT to build and run the image. See Building an image with z/OS Provisioning Toolkit.
If the following message is displayed during provisioning, ensure that you used the correct name for the usage type in the cics.properties file and that this name is set for the port allocation range in the Usage Type field in z/OSMF.
```
Unable to find free port
```
Be aware that the same message might be displayed if a port allocation range is not associated with the template, or simply because all the ports in the valid port ranges are in use.
Repeat step 4 to create more images that specify other usage types, and so use different port allocation ranges.