VIPADYNAMIC - VIPADISTRIBUTE statement

Enables (VIPADISTRIBUTE DEFINE) or disables (VIPADISTRIBUTE DELETE) the sysplex distributor function for a dynamic VIPA (defined on the same stack by a VIPADEFINE or VIPABACKUP statement) for which new connection requests can be distributed to other stacks in the sysplex. If you want to distribute FTP traffic, specify port 21 (or another designation according to which ports you are using for FTP) on the PORT parameter.

Parameters

DEFINE

Adds or replaces the designation of this dynamic VIPA (defined on the same stack by a VIPADEFINE or VIPABACKUP statement) as distributable. This is the default value.

DELETE

Deletes a previous designation of a dynamic VIPA as distributable.

DISTMETHOD

Specifies the distribution method to be used by the distributing stack.

BASEWLM

Specifies that Workload Manager (WLM) and policy information is used for this distributed DVIPA for incoming connection requests. Incoming connection requests are distributed according to relative WLM system weight preferences as modified by the Target Server Responsiveness (TSR) value, and possibly as modified by Service Policy Agent policies. The value DISTMETHOD BASEWLM is the default setting unless you specify GRE or ENCAP.

Restriction: You cannot specify DISTMETHOD BASEWLM if you specify GRE or ENCAP.

Rule: You must specify IPCONFIG SYSPLEXROUTING on all target systems to use this distribution method.

BASEWLM distribution method options:

PROCTYPE

This parameter is valid only when the distribution method is BASEWLM. zAAPs and zIIPs are specialty processors designed for specific application workloads. Some target applications can take advantage of these specialty processors. For workloads that use server-specific WLM weights, WLM typically returns a composite raw weight that takes into consideration how well the server is meeting its WLM goals with respect to the various types of processors the server is using. For workloads that use system-wide WLM recommendations, WLM is unaware of how a resource is utilizing the various processors. Instead, WLM returns a weight for each processor type that is based on the amount of displaceable capacity for this processor in the system as compared to the available capacity for this processor on the other target systems.

For applications that use specialty processors and receive WLM system weight recommendations, specify a PROCTYPE parameter to indicate the expected proportion of each type of processor that the target application's workloads should use. A composite recommendation is determined from these proportions. Each of the proportions should be expressed as a number in the range 0 - 99. Each proportion value is divided by the total to determine the processor usage pattern. To determine the processor proportions to configure, study your workload usage of assist processors by analyzing SMF records, using performance monitors reports, such as RMF™, and so on.

Possible values include:

CP x

The proportion of the workload that uses conventional processors.

ZAAP y

The proportion of the workload that uses zAAP processors.

ZIIP z

The proportion of the workload that uses zIIP processors.

For example, the value PROCTYPE CP 5 ZAAP 0 ZIIP 3 specifies a processor usage pattern such that 5/8 of the application's CPU utilization uses conventional processors (CP), and 3/8 of the application's CPU utilization uses zIIP processors.

For example, the value PROCTYPE CP 60 ZAAP 30 ZIIP 10, would specify a processor usage pattern such that 60% uses conventional processors (CP), 30% uses zAAP processors, and 10% uses zIIP processors.

The value PROCTYPE CP 1 ZAAP 0 ZIIP 0 is the default value; this value is used when the PROCTYPE parameter has never been specified. The default value indicates that 100% of the conventional processor weight (CP) should be considered when determining the composite weight (the application's workload does not use zIIP or zAAP processors). This value also disables an existing PROCTYPE value.

Specifying the PROCTYPE parameter without any parameters is equivalent to specifying the default values; you can use this setting disable an existing PROCTYPE value.

Restriction: When processor types are specified, at least one type must be specified with a nonzero value.

ROUNDROBIN

Specifies that WLM and policy information are not used to determine how to route future incoming connection requests for this distributed DVIPA. Incoming TCP connection requests are distributed in a round-robin fashion across the available TCP/IP stacks that are targets for each DVIPA/port combination and have at least one application server instance listening on the specified ports. This distribution method is not influenced by the number of server instances that are active on a target TCP/IP stack instance and listening on the same port (for example, SHAREPORT specified on the PORT reservation statement). In other words, a target TCP/IP stack that has multiple active servers on the same port does not receive more connection requests than a target stack that has a single instance of that server active. DISTMETHOD ROUNDROBIN is the default setting if GRE or ENCAP is specified.

Result: If a distribution target has a Target Server Responsiveness (TSR) value of 0, it is normally not used as a target for distribution. For more information about responsiveness monitoring, see z/OS Communications Server: IP Configuration Guide.

SERVERWLM

Specifies that server-specific WLM values should be collected for this group of DVIPA ports. If WLM server values can be collected for each target server, these values are used to distribute connections for this group of DVIPA ports [as modified by the Target Server Responsiveness (TSR) value, and possibly as modified by Service Policy Agent policies]. If all target servers do not provide the server-specific recommendations, then DISTMETHOD BASEWLM distribution is used instead. For more information about workload balancing and sysplex distribution, see z/OS Communications Server: IP Configuration Guide.

Rule: You must specify IPCONFIG SYSPLEXROUTING on all target systems to use this distribution method.

Result: zAAP and zIIP processor capacity is automatically included when SERVERWLM is specified and all systems in the sysplex are V1R9 or later.

Restriction: You cannot specify SERVERWLM if you specify GRE or ENCAP.

Port sharing

Specifying SHAREPORT on the PORT statement in the TCP/IP profile enables a group of servers to listen on the same port and thereby share the incoming workload. As new connections are received, the SHAREPORT algorithm distributes connections in a weighted round-robin fashion based on each server's Server accept Efficiency Fraction (SEF). By specifying SHAREPORTWLM on the PORT statement, connections are distributed in a weighted round-robin fashion based on the WLM server-specific recommendations, as modified by the Server accept Efficiency Fraction (SEF). If the shared port is a sysplex-distributed port and SERVERWLM is the distribution method that is being used, then SHAREPORTWLM should be coded on each target's PORT statement to take advantage of the new WLM server-specific recommendations when connections are received at the target; if it is not, new connections continue to be distributed using the existing SHAREPORT algorithm when they are received at the target.

Result: zAAP and zIIP processor capacity is automatically included when SHAREPORTWLM is specified and all systems in the sysplex are V1R9 or later.

SERVERWLM distribution method options:

ILWEIGHTING

This parameter is valid only when the distribution method is SERVERWLM.

The ILWEIGHTING parameter specifies the weighting factor that WLM uses when comparing displaceable capacity at different importance levels (ILs) as it determines a SERVERWLM recommendation for each system. The parameter value indicates how aggressively WLM should favor systems with displaceable capacity at low importance levels over systems with displaceable capacity at high importance levels. The higher the value specified for ILWEIGHTING the more a stack with displaceable capacity at lower importance levels is favored. See the internal load balancing information in z/OS Communications Server: IP Configuration Guide for more information about the effects of this parameter.

0

WLM ignores importance levels when comparing displaceable capacity. This is the default value.

1

WLM weights displaceable capacity that is at each successively lower importance level slightly higher than the capacity at the preceding importance level. The weighting increases proportionally to the square root of the difference between the two importance level values plus 1. This calculation provides a moderate bias when comparing displaceable capacity at different importance levels.

Guideline: If you specify any value other than the default value (0), for the first time, specify this value (1) initially.

2

WLM weights displaceable capacity that is at each successively lower importance level significantly higher than the capacity at the preceding importance level. The weighting increases proportionally to the difference between the two importance level values plus 1. This provides an aggressive bias when comparing displaceable capacity at different importance levels.

3

WLM weights displaceable capacity that is at each successively lower importance level significantly higher than the capacity at the preceding importance level. The weighting increases proportionally to the square of the difference between the two importance level values plus 1. This provides an exceptionally aggressive bias when comparing displaceable capacity at different importance levels.

PROCXCOST

This parameter is valid only when the distribution method is SERVERWLM.

zAAPs and zIIPs are specialty processors designed to off-load specific application workloads. Some target applications are designed to have a portion of their workload take advantage of these processors.

For server-specific recommendations, WLM calculates a composite weight based on a comparison, for each system, of the available capacity of each processor modified by the proportion of processor usage by the application. However, the composite weight does not consider that the conventional processor proportion on a system might be higher than normal because specialty processing capacity is constrained; a portion of the workload intended to run on a specialty processor ran on the conventional processor instead.

This parameter specifies a crossover cost which is applied to the zAAP or zIIP targeted workload that ran on the conventional processor; it reduces the conventional processor proportion which in turn reduces the composite weight for that system. This parameter can be used to cause WLM to favor systems that had less crossover (more of their workload running on the intended specialty processor) over systems that had more crossover. The higher the PROCXCOST crossover value, the more aggressively WLM recommendations favor systems with more specialty engine capacity which can reduce overall processing cost; however, if you use a PROCXCOST value that is too aggressive (high), overall workload performance for that service class might be sacrificed. The RMF Workload Activity Report shows the zAAP and zIIP processor utilization as well as how much crossover took place. Run this report before, and after, using the PROCXCOST parameter to better understand how this affects your overall workload performance.

Possible values include:

ZAAP x

The crossover cost of running targeted zAAP workload on a conventional processor instead of the zAAP processor, where x is an integer in the range 1 - 100. The higher the PROCXCOST zAAP value, the more aggressively the systems with less zAAP crossover occurring are favored. The default value is 1, which means that zAAP crossover is not considered.

ZIIP y

The crossover cost of running targeted zIIP workload on a conventional processor instead of the zIIP processor, where y is an integer in the range 1 - 100. The higher PROCXCOST zIIP value, the more aggressively the systems with less zIIP crossover are favored. The default value is 1, which means that zIIP crossover is not considered.

TARGCONTROLLED

Specifies that incoming connection requests are distributed using weights provided by the Tier 1 targets.

Restrictions:

• You can specify TARGCONTROLLED only when you specify GRE or ENCAP.
• You can specify TARGCONTROLLED only when you are distributing connections to DataPower® appliances.

WEIGHTEDACTIVE

Specifies that WLM and policy information are not used to determine how to route future incoming connection requests for this distributed DVIPA. Instead, distribution of incoming TCP connection requests is balanced across the targets such that the number of active connections on each target is proportionally equivalent to a configured active connection weight for each target.

You can specify the weight for each target on the DESTIP parameter after each target's IP address. If you configure the value DESTIP ALL, then the default weight 10 is used and the connection distribution goal is to have an equal number of active connections for each DESTIP target. For more information, see the DESTIP WEIGHTEDACTIVE options.

This distribution method is not influenced by the number of server instances that are active on a target TCP/IP stack instance and listening on the same port (SHAREPORT parameter specified on the PORT reservation statement). For example, when two target TCP/IP stacks are configured with the same active connection weight, if one of the targets has multiple active servers for that port and the other target has only one instance of that server active, both stacks initially receive the same number of connection requests.

Rule: You must specify IPCONFIG SYSPLEXROUTING on all target systems to use this distribution method.

HOTSTANDBY

Specifies that there is at least one backup (hot-standby) target and a preferred target stack. You must configure one preferred target and at least one hot-standby target. For information about configuring these targets, see the PREFERRED and BACKUP parameters under DESTIP HOTSTANDBY options.

The target to which connections are distributed is referred to as the active target. If AUTOSWITCHBACK is configured, then the preferred target is the active target if it is available and has not had any health problems. If the active target becomes unavailable, the hot-standby target becomes the new active target, and the unavailable target becomes a hot-standby target.

A target is unavailable if any of the following conditions are true:

• The target is not ready.
• The distributor does not have an active route to the target.
• The target is not healthy; there is a severe problem detected by one of the following health metrics:
  • The target server responsiveness (TSR) value is 0%
  • WLM reported abnormal terminations are 1000 out of 1000 total transactions
  • WLM reported health is 0%

Requirement: PREFERRED or BACKUP must be configured on the DESTIP parameter for each target after the dynamic XCF address. For more information, see the DESTIP HOTSTANDBY options.

Rule: IPCONFIG SYSPLEXROUTING must be specified on all target systems for this distribution method to be used.

Restrictions:

• You cannot configure DESTIP ALL with this distribution method.
• You cannot configure GREor ENCAP with this distribution method.
• TIMEDAFFINITY is ignored with this distribution method.

Result: In the Netstat VDPT/-O report, ACTIVE is displayed if this is currently the active target, and BACKUP is displayed if this is currently a hot-standby target. For more information about the Netstat VDPT/-O report, see z/OS Communications Server: IP System Administrator's Commands.

HOTSTANDBY distribution method options:

AUTOSWITCHBACK | NOAUTOSWITCHBACK

AUTOSWITCHBACK

Specifies that the distributor automatically switches distribution back to the preferred target when the preferred target becomes available. For example, if the preferred target becomes a standby target because its server is no longer ready, when the server is again in the LISTENING state, the distributor automatically switches back to the preferred target as the active target. This is the default value.

Automatic switchback does not occur if the preferred target initially became unavailable because it was not healthy (TSR, WLM abnormal terminations, WLM health). A standby target that had health problems while active can look healthy again because it is not processing new work.

NOAUTOSWITCHBACK

Specifies that you do not want the distributor to switch back to the preferred target when it becomes available.

HEALTHSWITCH | NOHEALTHSWITCH

HEALTHSWITCH

Specifies that the distributor automatically switches from the active target if the target is not healthy. This is the default value.

NOHEALTHSWITCH

Specifies that the distributor ignores health metrics, and switches from the active target only if the target is not ready or if the distributor does not have an active route to the target.

SYSPLEXPORTS

Causes coordinated sysplex-wide ephemeral port assignment to be activated for the distributed DVIPA on all stacks where the DVIPA is defined, including all active candidate target stacks and the distributing stack, for all TCP connection requests.

SYSPLEXPORTS must be specified on the first VIPADISTRIBUTE statement for a DVIPA. It cannot be enabled after a DVIPA has been marked for distribution. If enabled, it cannot be disabled until all distribution has been deleted for the DVIPA (except for quiescing the DVIPA on the target stacks).

If you send connection requests to SYPLEXPORTS-enabled distributed DVIPAs and a random ephemeral port with no associated listener, then this connection times out.

Rules:

• For Passive Mode FTP to be distributed, the SYSPLEXPORTS parameter must be specified.
• Always specify the PORT parameter when specifying the SYSPLEXPORTS parameter; the way dynamic port allocation interacts with the EZBEPORT vvtt structure inhibits distribution to more than one target.
• A server application on a target stack can bind to a distributed DVIPA and a port that is not defined in the PORT parameter of the VIPADISTRIBUTE statement.
• If EPHEMERALPORTS is specified on the TCPCONFIG statement, only ports within the EPHEMERALPORTS range are assigned on the local stack for SYSPLEXPORTS processing.

Restrictions:

• For sysplexports allocation to function correctly, the stacks involved must be connected to the same sysplex ports coupling facility structure.
• SYSPLEXPORTS is ignored if GRE or ENCAP is specified.

TIER1 groupname

This parameter indicates that the dynamic VIPA whose address is specified as an IP address on this statement is used to distribute incoming requests to z/OS® or non-z/OS targets (for example, DataPower appliances).

Rules:

• If you do not specify GRE or ENCAP, the targets are z/OS targets and the IP addresses specified on the DESTIP subparameter of this statement are dynamic XCF addresses.
• If you specify GRE or ENCAP, the targets are non-z/OS targets and the IP addresses specified on the DESTIP subparameter of this statement are not dynamic XCF addresses, but are the IP addresses of those Tier 1 targets.

The groupname value specifies the name of a cluster of equivalent server applications in the sysplex that the tier 1 targets might distribute the requests to. The groupname value can be 1 - 16 characters in length, must begin with an alphabetic character, and must not contain any national symbols, including @ or $. This value is used to correlate this statement with a corresponding TIER2 VIPADISTRIBUTE statement or statements. When TIER1 is specified, groupname is required, even if TIER2 definitions are not used.

CONTROLPORT port_number

Specifies the destination port number to be used when a control connection is being established to the Tier 1 target; a control connection is always established when GRE or ENCAP is configured. If CONTROLPORT is not specified, but GRE or ENCAP is specified, the default port number 1702 is used. See the DataPower configuration manuals for information about how to configure a control port.

Restrictions:

• You can specify CONTROLPORT only when you are distributing connections to non-z/OS targets.
• You can specify CONTROLPORT only when GRE or ENCAP is specified.
• The same port number (whether explicitly specified or specified by default) must be used on all VIPADISTRIBUTE statements that specify a CONTROLPORT value or that require a default port value. When a VIPADISTRIBUTE statement specifying a CONTROLPORT port_number (or requiring the default port value) has been encountered, any subsequent VIPADISTRIBUTE statement specifying a different port number is rejected.

GRE

Indicates that generic routing encapsulation (GRE) is used when distributing requests to the Tier 1 targets.

Restrictions:

• This parameter applies to IPv4 only.
• You can specify GRE only when you are distributing connections to non-z/OS targets.
• You can specify GRE only when TIER1 is specified.
• When GRE is specified, the following parameters on the VIPADISTRIBUTE statement are ignored:
  • SYSPLEXPORTS
  • OPTLOCAL
• When GRE is specified, the following DISTMETHOD parameters cannot be specified:
  • BASEWLM
  • SERVERWLM
• If the client is local to the distributing stack and it binds to inaddr_any or it uses an implicit bind, you must ensure that source IP address selection does not choose to use the distributed DVIPA destination as the source IP address for the connect() call. In the following example, source IP address selection will use the distributed DVIPA destination (DVIPA1) for the source because it is locally owned and advertised by the sysplex distributor. Because the SYN is routed by the sysplex distributor to a DataPower appliance, the packet is encapsulated in a GRE header:

  GRE		Inner IP header
  Source IP	Dest IP	Source IP	Dest IP
  XCF@	DataPower IP@	Distributed DVIPA1	Distributed DVIPA1

  After the GRE header is stripped away at the DataPower appliance, the connect() call will hang because the DataPower routing logic assumes that the packet should remain local because the source IP address (DVIPA1) is locally defined on the appliance as a non-advertised IP address.

  The source IP address must be routable by the DataPower appliance. You can use the SRCIP statement to select an appropriate source IP address for the client application.

  For more information about source IP selection, see z/OS Communications Server: IP Configuration Guide. For more information about the SRCIP statement, see SRCIP statement.

Tip: If you specify GRE, a control connection to the Tier 1 target is always established, using the CONTROLPORT port number as the destination port.

ENCAP

Indicates that routing encapsulation is used when distributing requests to the Tier 1 targets.

Restrictions:

• This parameter applies to IPv6 only.
• You can specify ENCAP only when you are distributing connections to non-z/OS targets.
• You can specify ENCAP only when TIER1 is specified.
• If you specify ENCAP, the following parameters on the VIPADISTRIBUTE statement are ignored:
  • SYSPLEXPORTS
  • OPTLOCAL
• If you specify ENCAP, you cannot specify the following DISTMETHOD parameters:
  • BASEWLM
  • SERVERWLM
• If the client is local to the distributing stack and it binds to the unspecified IPv6 address (in6addr_any), or if it uses an implicit bind, you must ensure that source IP address selection does not choose to use the distributed DVIPA destination as the source IP address for the connect() call. In the following example, source IP address selection will use the distributed DVIPA destination (DVIPA1) for the source because it is locally owned and advertised by the sysplex distributor. Because the SYN is routed by the sysplex distributor to a DataPower appliance, the packet is encapsulated in the outer IP header:

  OuterIP header		Inner IP header
  Source IP	Dest IP	Source IP	Dest IP
  XCF@	DataPower IP@	Distributed DVIPA1	Distributed DVIPA1

  After the outer IP header is stripped away at the DataPower appliance, the connect() call will hang because the DataPower routing logic assumes that the packet should remain local because the source IP address (DVIPA1) is locally defined on the appliance as a non-advertised IP address.

  The source IP address must be routable by the DataPower appliance. You can use the SRCIP statement to select an appropriate source IP address for the client application.

  For more information about source IP selection, see z/OS Communications Server: IP Configuration Guide. For more information about the SRCIP statement, see SRCIP statement.

Tip: If you specify ENCAP, a control connection to the Tier 1 target is always established, using the CONTROLPORT port number as the destination port.

TIER2 groupname

This parameter indicates that the dynamic VIPA whose address is specified as an IP address on this statement is used to distribute incoming requests from Tier 1 targets to the group of server applications that is named.

The groupname value specifies the name of a cluster of equivalent server applications in the sysplex that the Tier 1 targets might distribute the requests to. It is used to correlate this statement with a corresponding TIER1 VIPADISTRIBUTE statement.

The groupname value can be 1 - 16 characters in length, must begin with an alphabetic character, and must not contain any national symbols, including @ or $.

TIMEDAFFINITY seconds

Specifies whether or not a connection from a client (as identified by source IP address) to a particular server instance of several served by sysplex distributor shall establish an affinity for future connections from the same client (IP address) to the same Distributed DVIPA and ports. Valid values are in the range 0 to 9999. A value of 0, the default, means that no affinity is established when a new connection request is distributed to a particular server application instance by sysplex distributor. A nonzero value means that when a connection from a client is routed to a particular server instance, any subsequent connections from the same client (identified by source IP address) to the same Distributed DVIPA and ports are routed to the same server instance until the specified number of seconds have elapsed after the last such connection was closed.

Restriction: Under some circumstances, a client's affinity with a specific target application server instance might be terminated prior to the specified time interval. This can occur if the key resources needed to satisfy new client TCP connection requests are not available. See z/OS Communications Server: IP Configuration Guide for more information.

If the TIMEDAFFINITY parameter is not initially specified on a VIPADISTRIBUTE statement, this indicates that timed affinity is not being used for the distributed DVIPA and ports, which is the same as specifying TIMEDAFFINITY 0.

Restriction: The TIMEDAFFINITY parameter cannot be specified with the OPTLOCAL keyword.

OPTLOCAL value | NOOPTLOCAL

NOOPTLOCAL

Causes target stacks to send locally originating connection requests to the sysplex distributor stack even when both endpoints reside on the same target stack. This is the default value.

OPTLOCAL value

Causes target stacks to optimize sysplex connections for which both endpoints reside on the same stack. When this value is specified, target stacks should bypass sending connection requests to the sysplex distributor stack for connections to a distributed DVIPA and port pair that reside locally, and instead process the connection locally using local optimizations. The local target stack continues to favor the local stack unless conditions on the local stack become unfavorable as defined by the value specified. If this happens, connections to this distributed DVIPA and port pair are sent to the sysplex distributor stack for appropriate work load balancing.

Restrictions:

• OPTLOCAL cannot be specified with the TIMEDAFFINITY keyword.
• OPTLOCAL is ignored if GRE or ENCAP is specified.

value

An integer in the range 0 - 16. The values 0 and 1 are special values, and values 2 - 16 are used as multipliers against the raw WLM weights.

A value of 0 indicates that connections originating from a target stack within the sysplex should always bypass sending the connection request to the sysplex distributor. The relative capacities of other target stacks within the sysplex are not considered in determining whether the connection should remain local.

A value of 1 indicates that connections originating from a target stack within the sysplex should always bypass sending the connection request to the sysplex distributor as long as the WLM weight for the server on the local stack is not 0. This is the default value if OPTLOCAL is specified without a value.

If a value in the range 2 - 16 is specified, the value is used as a multiplier against the local target stack's raw WLM weight to cause it to be favored over the other target stacks. The relative capacities of the other target stacks within the sysplex are considered in determining which stack should process the connection. The higher the value specified, the more the local stack is favored over other target stacks.

Regardless of the value specified on the OPTLOCAL parameter, if no local server is available, or the SEF is less than 75 or the abnormal transaction completions is greater than 250, or the health indicator is less than 75, connections are sent to the distributing stack.

Result: If the configured distribution method is ROUNDROBIN, WEIGHTEDACTIVE, or HOTSTANDBY, the OPTLOCAL value is forced to 0.

ipv4_addr

The specific IPv4 address for which the designation as distributable is to be deleted or defined.

Rule: An IPv4 address is not allowed if TIER1 ENCAP is specified.

ipv6_intfname

The specific IPv6 interface for which the designation as distributable is to be deleted or defined.

Rule: An IPv6 interface is not allowed if TIER1 GRE is specified.

PORT num | num-num

Specifies one or more individual ports, ranges of ports, or a combination of individual ports and ranges. Valid values for num are in the range of 1 - 65535. For a port range, the value for the second port must be greater than the first.

If the PORT parameter is specified, servers that bind to the specified DVIPA, the IPv4 INADDR_ANY address, or to the IPv6 unspecified address (in6addr_any) and one of the specified ports, cause the target stack to become eligible to receive connection requests.

The PORT parameter can also be omitted entirely from the VIPADISTRIBUTE statement. If the PORT parameter is omitted, then any server that binds a socket to the distributed DVIPA and a specific (nonzero) port, and establishes that socket as a listening socket, is eligible for connection workload balancing. The following methods can be used to bind a socket to the distributed DVIPA and a specific (nonzero) port:

1. If available, use a socket option provided by the server application to override the INADDR_ANY address and to specify a distributed DVIPA address for the listening port.
2. Code a BIND parameter that specifies a distributed DVIPA for the listening port in the TCP/IP profile PORT statement.
3. Use the TCP/IP profile SRCIP statement to specify a job name for the server application, the distributed DVIPA address, and the SERVER option. The listening port for the server application will be associated with the distributed DVIPA address.

Rules:

• When the PORT parameter is omitted from the VIPADISTRIBUTE statement and a specific (nonzero) port is not specified on the bind for the distributed DVIPA, then any ports that are bound to the distributed DVIPA are eligible for distribution.
• When the PORT parameter is specified, at least one port or port range must be specified. The maximum number of ports that is specified, including all individual ports and all ports within ranges, cannot exceed 64.
• Always specify the PORT parameter when specifying the SYSPLEXPORTS parameter. For the ports omitted from the PORT parameter, connection setup delays and connection timeouts might occur when there are no active listeners in the target stacks.
• For the ports specified in the PORT parameter for a distributed DVIPA, reserve them in the PORT statement in all target stacks associated with the distributed DVIPA so that ineligible server applications will not use them.

Requirement: If you specify TIER1 GRE or TIER1 ENCAP, you must specify the PORT parameter.

DESTIP dynxcfip

Specifies the dynamic XCF address (IPCONFIG DYNAMICXCF) of the TCP/IP stacks in the sysplex that are to be target stacks for the dynamic VIPA. The target stacks are candidates for receiving new incoming connection requests. See the PORT keyword for an explanation of how a candidate target stack becomes eligible to receive connection requests. If the VIPAROUTE statement specifies a target IP address for dynxcfip, but no route exists from the distributor to the target stack, that target stack is not considered for distribution, and the distributor treats this as it does when the dynamic XCF interface becomes inactive.

A maximum of 32 destination (target) dynamic XCF addresses can be specified.

Rules:

• If an IPv4 address is specified for this VIPADISTRIBUTE statement, then all of the addressees specified by the dynxcfip value must also be IPv4 addresses.
• If an IPv6 interface name is specified for this VIPADISTRIBUTE statement, then all of the addressees specified by the dynxcfip value must also be IPv6 addresses.

DESTIP targetip

When you specify TIER1 GRE or TIER1 ENCAP, this parameter specifies the IP address of non-z/OS hosts (for example, DataPower) appliances that are to be targets for the dynamic VIPA. The targets are candidates to receive new incoming connection requests.

When you specify TIER1 without specifying GRE or ENCAP, this parameter specifies the dynamic XCF address (IPCONFIG DYNAMICXCF) of the TCP/IP stacks in the sysplex that are to be target stacks for the dynamic VIPA. The target stacks are candidates to receive new incoming connection requests.

A maximum of 32 Tier 1 target IP addresses can be specified.

Requirement: You must specify TIER1 and either GRE or ENCAP when specifying the IP address of a non-z/OS host.

Rules:

• If an IPv4 address is specified for this VIPADISTRIBUTE statement, then all of the addressees specified by the targetip value must also be IPv4 addresses.
• If an IPv6 interface name is specified for this VIPADISTRIBUTE statement, then all of the addressees specified by the targetip value must also be IPv6 addresses.
• IPv6 addresses are not valid if TIER1 GRE is specified.
• IPv4 addresses are not valid if TIER1 ENCAP is specified.

DESTIP WEIGHTEDACTIVE options:

WEIGHT value

This parameter is configured following a DESTIP targetip or dynxcfip value.

This parameter has meaning only if the distribution method is WEIGHTEDACTIVE; it is ignored if this is not the distribution method. The weight is used by the distributor to determine the proportion of incoming requests to route to this target such that the number of active connections on each target is proportionally equivalent to the configured weight for each target. Valid values are in the range 1 - 99.

For example, if target 1 has a weight of 10 and target 2 has a weight of 90, then the connection distribution goal is to have 9 times as many active connections on target 2 as on target 1, or 10% of the active connections on target 1 and 90% of the active connections on target 2. If a weight is not specified, the default value of 10 is used. If the distribution method is WEIGHTEDACTIVE and weights are not configured for any targets, the goal is to have an equal number of active connections on each target.

Guidelines: Although weights can be in the range 1- 99, it is preferred to use weights that are greater or equal to 10. This is because the target server health metrics (Target Server Responsiveness [TSR] fractions) abnormal terminations, and the health indicator fractions are used to reduce the weight when these values are not optimal. By specifying weights greater than or equal to 10, these metrics can be applied without losing the original weight distinctions between targets. For example, if target 1 has a weight of 2, target 2 has a weight of 1, and a TSR for target 1 of 90% is applied, target 1 has a reduced weight of 1 (equal to target 2), but if target 1 has a weight of 20 and target 2 has a weight of 10, then when the TSR of 90% is applied to target 1, it has a weight of 18 (weight reduced, but it is still preferred over target 2).

If your workload has a low connection arrival rate (less than 100 connections per minute), and typically has a low number of active connections (less than 1000 active connections), you will get the most accurate distribution if you configure each weight so that it is a multiple of 10.

DESTIP HOTSTANDBY options:

PREFERRED

Specify this parameter after the dynamic XCF address (dynxcfip) on the DESTIP parameter. This parameter specifies that this address is the preferred target when the distribution method is HOTSTANDBY. If you configure AUTOSWITCHBACK, then the preferred target is the active target if it is available and has not had any health problems. If the active target becomes unavailable, the distributor switches to use a hot-standby target; the active target becomes a hot-standby target and the selected hot-standby target becomes the active target.

Restriction: You can specify this parameter only if you specify DISTMethod HOTSTANDBY.

BACKUP rank

Specify this parameter after the dynamic XCF address (dynxcfip) on the DESTIP parameter. This parameter specifies that this address is one of the backup targets when the distribution method is HOTSTANDBY.

The rank is used to determine which backup target is selected if the preferred target becomes unavailable. The backup with the highest rank is used. Valid values for rank are in the range 1 - 254; the default value is 1.

Restriction: You can specify this parameter only if you specify DISTMethod HOTSTANDBY.

DESTIP ALL

All TCP/IP stacks in the sysplex that have defined a dynamic XCF address of the same type as the IP address specified by the ipv4_addr or ipv6_intfname values in this VIPADISTRIBUTE statement are target stacks for the dynamic VIPA and for ports specified on this profile statement. If the distribution method WEIGHTEDACTIVE is being used, the default weight 10 is assumed for all targets; the goal is to have an equal number of active connections on each target.

Restrictions: .

• • DESTIP ALL cannot be specified when GRE or ENCAP is specified, or when the distribution method is HOTSTANDBY.
  • When DESTIP ALL or DESTIP dxcfaddr is specified, there is a limitation that only 32 targets can be used.

Steps for modifying

• To add ports (if the active VIPADISTRIBUTE statement has the PORT parameter coded) or destination stacks for a distributed DVIPA, use another VIPADISTRIBUTE statement to specify the additional port or ports and destination stacks. Ports and destination stacks for a distributed VIPA are cumulative, up to the maximum number allowed (64 for ports and 32 for destination stacks).
• To remove a port or a destination stack for IPv4, or both, for a distributed VIPA, use one of the following:

  VIPADISTRIBUTE DELETE ipaddr PORT port_num ... DESTIP dynxcfip ...

  VIPADISTRIBUTE DELETE ipaddr PORT port_num DESTIP ALL

  For IPv6, use one of the following:

  VIPADISTRIBUTE DELETE ipv6_intfname PORT port_num ... DESTIP dynxcfip

  VIPADISTRIBUTE DELETE ipv6_intfname PORT port_num DESTIP ALL

• To end distribution for a VIPA, use one or more VIPADISTRIBUTE DELETE statements to delete every port and destination stack that is currently configured for this VIPA. These changes are communicated to any stacks backing up the distribution of this DVIPA, unless the backup stack has its own VIPADISTRIBUTE statement coded.
• If ports are currently assigned for distribution dynamically for this Distributed DVIPA (PORT parameter omitted from the VIPADISTRIBUTE DEFINE), then VIPADISTRIBUTE DELETE can be used only to stop distribution for a target TCP/IP or for the Distributed DVIPA as a whole. VIPADISTRIBUTE DELETE cannot be used to stop distribution for a port with a Distributed DVIPA where ports are added dynamically.
• To specify certain ports for distribution when a distributed DVIPA is allowing distribution ports to be assigned dynamically (the active VIPADISTRIBUTE statement has no PORT parameter), you must first delete the VIPADISTRIBUTE statement (without PORT parameter). You can then code a VIPADISTRIBUTE statement with the PORT parameter. Existing connections to server instances are not affected. However, a server listening socket bound to a port which is not in the current PORT statement does not receive additional work.
• To allow dynamic port specification by having servers listening on ports when the active VIPADISTRIBUTE statement has a PORT parameter coded, you must first delete the VIPADISTRIBUTE statement (with PORT parameter). You can then code a VIPADISTRIBUTE statement without the PORT parameter. Existing connections are not affected. Note that when the VIPADISTRIBUTE statement is specified without the PORT parameter, only servers that bind explicitly to the distributed DVIPA are eligible for workload distribution for that distributed DVIPA.
• To modify the OPTLOCAL option on the VIPADISTRIBUTE statement, respecify the VIPADISTRIBUTE statement with the new option value in a data set referenced by a VARY TCPIP,,OBEYFILE command. You can specify NOOPTLOCAL to dynamically stop OPTLOCAL processing.
• If the value TIMEDAFFINITY 0 is specified for a distributed DVIPA and ports for which a nonzero TIMEDAFFINITY value was in effect, no future affinities are established for new clients connecting to the distributed DVIPA and ports covered by the VIPADISTRIBUTE statement. Existing client affinities are not affected.
• If a nonzero TIMEDAFFINITY value is specified for an existing distributed DVIPA with active connections, affinities are established only for connections that are received at the distributing stack after the processing of the VARY TCPIP,,OBEYFILE command that established the nonzero TIMEDAFFINITY value. Existing connections do not automatically have an affinity established for the respective client.
• To change the distribution method being used, respecify the VIPADISTRIBUTE statement with the new DISTMETHOD option in a data set referenced by a VARY TCPIP,,OBEYFILE command. If the new distribution method is WEIGHTEDACTIVE:
  • Specify the WEIGHT keyword and the desired active connection weight value after each DESTIP dynamic XCF address.
  • If the active connection weight is not specified a default value of 10 is assumed.
  • If DESTIP ALL is specified, the active connection weight cannot be specified. A goal of having an equal number of active connections on all targets is used.
• To change the active connection weights being used for the targets when the distribution method is WEIGHTEDActive, in a data set referenced by a VARY TCPIP,,OBEYFILE command, respecify the VIPADISTRIBUTE statement with the WEIGHT keyword and the desired active connection weight value following each DESTIP dynamic XCF address. If the active connection weight is not specified, a default value of 10 is assumed.
• To change the PROCTYPE values being used with BASEWLM, in a data set referenced by a VARY TCPIP,,OBEYFILE command, respecify the VIPADISTRIBUTE statement with the PROCTYPE values for each processor type. If PROCTYPE is not specified, the previous values for PROCTYPE are used.
• To stop using PROCTYPE values, in a data set referenced by a VARY TCPIP,,OBEYFILE command, respecify the VIPADISTRIBUTE statement with the PROCTYPE values of CP 1 zAAP 0 zIIP 0, or simply PROCTYPE. This is the default usage of BASEWLM; only the general CPU weight that is returned by WLM is considered.
• To change the PROCXCOST values that are being used with SERVERWLM respecify the VIPADISTRIBUTE statement with the PROCXCOST values for each processor type in a data set referenced by a VARY TCPIP,,OBEYFILE command. If PROCXCOST is not specified, then the TCP/IP stack uses the previous values for PROCXCOST when it receives a server-specific WLM recommendation.
• To change the ILWEIGHTING value being used with SERVERWLM, respecify the VIPADISTRIBUTE statement with the ILWEIGHTING value in a data set referenced by a VARY TCPIP,,OBEYFILE command. If ILWEIGHTING is not specified, then TCP/IP stack uses the previous values for ILWEIGHTING when it gets a server-specific WLM recommendation.