MODIFY command: z/OS Load Balancing Advisor

You can control the z/OS® Load Balancing Advisor from the operator console using the MODIFY command.

Format


>>-+-MODIFY-+--procname,---------------------------------------->
   '-F------'              

>--+-DEBug,Level=debuglevel---------------------------+--------><
   '-DISplay,-+-DEBug-------------------------------+-'   
              |                       .-,MAX=100--. |     
              '-LB-+----------------+-+-----------+-'     
                   +-,Index=lbindex-+ +-,MAX=*----+       
                   '-,Index=ALL-----' '-,MAX=recs-'

Parameters

procname: The member name of the cataloged procedure used to start the z/OS Load Balancing Advisor.
DEBug,Level=debuglevel: Changes the Advisor debug level. The needed debug level is debuglevel. See Debug settings and corresponding syslogd priority levels in the z/OS Communications Server: IP Diagnosis Guide and the Advisor debug_level statement in the z/OS Communications Server: IP Configuration Reference for details about valid Advisor debug levels.
DISplay,DEBug: Displays the debug level in effect for the Advisor.
DISplay,LB: Displays a summary of connected load balancers. The universally unique identifier (UUID), health value, flags, and an index are shown for each connected load balancer. The index will remain the same as long as the load balancer is connected.
DISplay,LB,MAX=recs: Displays a summary of connected load balancers. The number of records (load balancers) displayed is limited by the MAX=recs parameter. The default is 100. If MAX=* is specified, then all connected load balancers are displayed.
DISplay,LB,Index=lbindex: Displays all registered groups including detailed member data for the identified load balancer or for all connected load balancers (by specifying the ALL parameter). The lbindexvalue is the decimal index shown in the display of all load balancers. If you specify the ALL parameter, detailed member data for all connected load balancers is displayed.
DISplay,LB,Index=lbindex,MAX=recs: Displays all registered groups including detailed member data for the identified load balancer or for all connected load balancers (by specifying the ALL parameter). The lbindex is the decimal index shown in the display of all load balancers. If you specify the ALL parameter, detailed member data for all connected load balancers is displayed. The number of records (members) displayed is limited by the MAX=recs parameter. The default value is 100. If MAX=* is specified, then all members are displayed.

Example 1 — The modify display LB command summarizes all load balancers that have connected to the Advisor.

F LBADV,DISP,LB                
EZD1242I LOAD BALANCER SUMMARY 
LB INDEX      : 00        UUID      : 637FFF175C           
 IPADDR..PORT : 10.42.105.154..50005                        
 HEALTH       : 20        FLAGS     : NOCHANGE PUSH TRUST  
LB INDEX      : 01        UUID      : 207FFF175C           
 IPADDR..PORT : 10.42.105.60..50006                        
 HEALTH       : 7F        FLAGS     : PUSH TRUST  
2 OF 2 RECORDS DISPLAYED

LB INDEX

Reference number used solely as the lbindex value on the MODIFY,DISPLAY,LB,INDEX= command. The same reference number is used for a load balancer as long as it is connected.

UUID

A hexadecimal value of the universally unique identifier assigned by the load balancer. This byte array can be up to 64 bytes in length.

IPADDR..PORT

The remote IP address and port at which the Advisor is connected to this load balancer. The IP address can be an IPv4 or an IPv6 address.

HEALTH

A hexadecimal value supplied by the load balancer that indicates the general health of the load balancer. Valid values are in the range 0 – X'7F'.

FLAGS

Flags that are set are displayed. Flag values are:

NOCHANGE: The Advisor sends only weights that have changed to the load balancer.
PUSH: The Advisor sends weights to the load balancer when any weights change.
TRUST: The load balancer trusts member applications to register themselves. Ignored by the Advisor.

Example 2 — The modify display command supplies details about a specific load balancer. The load balancer is identified using the index shown in the output of the modify display LB command. For each group of target applications, the display shows each active registered instance of the group in the sysplex.

F LBADV,DISP,LB,I=0                                          
EZD1243I LOAD BALANCER DETAILS                            
LB INDEX      : 00        UUID      : 637FFF175C             
 IPADDR..PORT : 10.42.105.154..50005                          
 HEALTH       : 20        FLAGS     : NOCHANGE PUSH TRUST    
 GROUP NAME   : SYSTEMFARM
  GROUP FLAGS : BASEWLM
  IPADDR..PORT: 10.42.154.105..0                              
   SYSTEM NAME: MVS209    PROTOCOL  : 000  AVAIL     : YES   
   WLM WEIGHT : 00040     CS WEIGHT : 100  NET WEIGHT: 00001 
     Raw           CP: 40  zAAP: 60  zIIP: 00
     Proportional  CP: 40  zAAP: 00  zIIP: 00
   FLAGS      :                                              
  IPADDR..PORT: 10.42.105.60..0                               
   SYSTEM NAME: VIC007    PROTOCOL  : 000  AVAIL     : YES   
   WLM WEIGHT : 00050     CS WEIGHT : 100  NET WEIGHT: 00001 
     Raw           CP: 50  zAAP: 00  zIIP: 00
     Proportional  CP: 00  zAAP: 00  zIIP: 00
      FLAGS      :                                              
  IPADDR..PORT: 10.42.105.22..0                               
   SYSTEM NAME: N/A       PROTOCOL  : 000  AVAIL     : NO    
   WLM WEIGHT : 00000     CS WEIGHT : 000  NET WEIGHT: 00000 
     Raw           CP: 00  zAAP: 00  zIIP: 00
     Proportional  CP: 00  zAAP: 00  zIIP: 00
   FLAGS      : NOTARGETSYS                                  
  IPADDR..PORT: 10:1::4:5..0                                 
   SYSTEM NAME: MVS209    PROTOCOL  : 000  AVAIL     : NO    
   WLM WEIGHT : 00040     CS WEIGHT : 000  NET WEIGHT: 00000 
     Raw           CP: 40  zAAP: 60  zIIP: 00
     Proportional  CP: 40  zAAP: 00  zIIP: 00
   FLAGS      : NOTARGETIP                                   
 GROUP NAME   : UDP_SERVER_FARM       
  GROUP FLAGS : SERVERWLM
  IPADDR..PORT: 10.42.154.105..7777                           
   SYSTEM NAME: MVS209    PROTOCOL  : UDP  AVAIL     : YES   
   WLM WEIGHT : 00021     CS WEIGHT : 100  NET WEIGHT: 00001 
     Raw           CP: 20  zAAP: 22  zIIP: 00
     Proportional  CP: 10  zAAP: 11  zIIP: 00
   ABNORM     : 00200     HEALTH    : 100
   FLAGS      :                                              
  IPADDR..PORT: 2001:DB8::10:5:6:2..7777                             
   SYSTEM NAME: MVS209    PROTOCOL  : UDP  AVAIL     : YES   
   WLM WEIGHT : 00021     CS WEIGHT : 100  NET WEIGHT: 00001 
     Raw           CP: 25  zAAP: 18  zIIP: 00
     Proportional  CP: 10  zAAP: 11  zIIP: 00
   FLAGS      :                                             
  IPADDR..PORT: 10.42.105.60..7777                            
   SYSTEM NAME: VIC007    PROTOCOL  : UDP  AVAIL     : YES   
   WLM WEIGHT : 00045     CS WEIGHT : 100  NET WEIGHT: 00002 
     Raw           CP: 50  zAAP: 18  zIIP: 00
     Proportional  CP: 30  zAAP: 15  zIIP: 00
   FLAGS      :                                           
 GROUP NAME   : CICS_SERVER_FARM
  GROUP FLAGS : BASEWLM
  ProcType    : 
    CP : 60  zAAP: 40  zIIP: 00
  IPADDR..PORT: 10.42.154.105..8888
   SYSTEM NAME: MVS209    PROTOCOL  : TCP  AVAIL     : YES
   WLM WEIGHT : 00048     CS WEIGHT : 100  NET WEIGHT: 00001
     Raw           CP: 40  zAAP: 60  zIIP: 00
     Proportional  CP: 24  zAAP: 24  zIIP: 00    
   FLAGS      :
  IPADDR..PORT: 10.42.105.60..8888
   SYSTEM NAME: VIC007    PROTOCOL  : TCP  AVAIL     : YES
   WLM WEIGHT : 00054     CS WEIGHT : 100  NET WEIGHT: 00001 
     Raw           CP: 50  zAAP: 60  zIIP: 00
     Proportional  CP: 30  zAAP: 24  zIIP: 00
   FLAGS
  IPADDR..PORT: 10.42.105.22..8888
   SYSTEM NAME: N/A       PROTOCOL  : TCP  AVAIL     : NO    
   WLM WEIGHT : 00000     CS WEIGHT : 000  NET WEIGHT: 00000 
     Raw           CP: 00  zAAP: 00  zIIP: 00
     Proportional  CP: 00  zAAP: 00  zIIP: 00 
   FLAGS      : NOTARGETSYS
  IPADDR..PORT: 10:1::4:5..8888                                
   SYSTEM NAME: MVS209    PROTOCOL  : TCP  AVAIL     : NO    
   WLM WEIGHT : 00048     CS WEIGHT : 000  NET WEIGHT: 00001 
     Raw           CP: 40  zAAP: 60  zIIP: 00
     Proportional  CP: 24  zAAP: 24  zIIP: 00    
   FLAGS      : NOTARGETIP
7 OF 7 RECORDS DISPLAYED

For explanations of LB INDEX, UUID, IPADDR..PORT, HEALTH, and FLAGS see Example 1.

GROUP

The name of a group of related target applications. The group name is a UTF-8 string displayed in EBCDIC on the MVS™ console. Any non-displayable character is displayed as a question mark (?).

GROUP FLAGS

Flags that are currently applied to the group as a whole. Flag values are:

BASEWLM: Indicates that system WLM recommendations are being used to calculate the net weight for each member of the group.
BASEWLM*: Indicates that SERVERWLM was coded on the Advisor WLM statement or was specified for this group on the PORT_LIST Advisor statement in order to use server-specific WLM recommendations. However, the Advisor is using system WLM recommendations instead to calculate the net weight for each member of the group. This can occur if one or more of the Agents owning the members within the group does not support server-specific WLM recommendations.
SERVERWLM: Indicates that server-specific WLM recommendations are being used to calculate the net weight for each member of this group.

proctype

When BASEWLM recommendations are configured, the proctype value indicates the expected proportion of each type of processor that a target application's workloads will consume. A composite recommendation is determined from these proportions. A PROCTYPE value can be configured on the port_list or wlm statement; when this value is not configured, it assumes a default value to indicate that the composite recommendations include only the general CP weight.

CP: The expected general CP utilization proportion that will be consumed by the applications.
zAAP: The expected zAAP utilization proportion that will be consumed by the applications.
zIIP: The expected IBM® System z9® or later Integrated Information Processor (zIIP) utilization proportion that will be consumed by the applications.

Restrictions:

zAAP and zIIP weight recommendations are available only if all systems in the sysplex are z/OS release V1R9 or later. If all systems in the sysplex are not z/OS release V1R9 or later, only CP weights are considered when determining a composite weight recommendation.
zAAP and zIIP weight recommendations are not used when determining the composite weight for system members.

IPADDR..PORT

Indicates the IP address and port to which the target application is bound. This is the first of several lines relating to the same target application. If this represents a system member, then IPADDR represents an IP address belonging to a TCP/IP stack on one of the MVS systems in the sysplex, and the PORT will be 0.

SYSTEM NAME

Indicates the MVS system name of the MVS system where the application exists. If this is a system member, this indicates the MVS system name of the MVS system that owns the IP address.

PROTOCOL

Indicates the protocol that the application is using. If the protocol is not TCP or UDP, the decimal number of the protocol is displayed. For system members, this will be 0.

AVAIL

Indicates whether the member is available for new workload distribution. A value of YES indicates that the Advisor considers the application available for load balancing. A value of NO indicates that the Advisor recommends that the application not be considered for load balancing.

WLM WEIGHT

Indicates the Workload Manager weight value for the MVS system or the server-specific WLM weight based on the BASEWLM or SERVERWLM group flag. This value is in the range 0 – 64. This value is the composite weight; it is the sum of the displayed proportional CP, zAAP, and zIIP weights for this member.

CP

When the distribution method is BASEWLM the following apply:

The Raw value is the WLM system general CP weight recommendation. The value is based on the amount of displaceable general CPU capacity on this system as compared to the other target systems.
The Proportional value is the Raw value modified by the expected general CP utilization proportion configured on the portlist and wlm statement for this application.

When the distribution method is SERVERWLM the following apply:

The Raw value is the WLM server-specific general CP recommendation. This is the amount of displaceable general CPU capacity based on the application workload's importance (as defined by the WLM policy) as compared to the other target systems.
The Proportional value is the Raw value modified by the proportion of general CP capacity that is currently being consumed by the application's workload as compared to the other processors (zAAP and zIIP).

zAAP

When the distribution method is BASEWLM the following apply:

The Raw value is the WLM system zAAP weight recommendation. This value is based on the amount of displaceable zAAP capacity on this system as compared to the other target systems.
The Proportional value is the Raw value modified by the expected zAAP utilization proportion configured on the portlist and wlm statement for this application.

When the distribution method is SERVERWLM the following apply:

The Raw value is the WLM server-specific zAAP recommendation. This value is the amount of displaceable zAAP capacity based on the application workload's importance (as defined by the WLM policy) as compared to the other target systems.
The Proportional value is the Raw value modified by the proportion of zAAP capacity that is currently being consumed by the application's workload as compared to the other processors (general CPU and zIIP).

zIIP

When the distribution method is BASEWLM the following apply:

The Raw value is the WLM system zIIP weight recommendation. This value is based on the amount of displaceable zIIP capacity on this system as compared to the other target systems.
The Proportional value is the Raw value modified by the expected zIIP utilization proportion configured on the portlist and wlm statements for this application.

When the distribution method is SERVERWLM the following apply:

The Raw value is the WLM server-specific zIIP recommendation. This value is the amount of displaceable zIIP capacity based on the application workload's importance (as defined by the WLM policy) as compared to the other target systems.
The Proportional value is the Raw value modified by the proportion of zIIP capacity that is currently being consumed by the application's workload as compared to the other processors (general CPU and zAAP)

Restrictions:

zAAP and zIIP weight recommendations are available only if all systems in the sysplex are z/OS release V1R9 or later. If all systems in the sysplex are not z/OS release V1R9 or later, only CP weights are considered when determining a composite weight recommendation.
zAAP and zIIP weight recommendations are not used when determining the composite weight for system members.

CS WEIGHT

Indicates the weight value recommended by the Agent. The range is 0 – 100, with a higher weight indicating that the application is able to handle more work than an application with a lower weight. One exception is that when the Agent is gathering historical data for an application (which takes 2 update intervals), the weight will be 100 and the NODATA flag will be set.

NET WEIGHT

Indicates the relative weight of this application in the sysplex. A higher weight indicates that an application can handle more workload than a lower weight application in the same group. This weight is based upon the WLM weight, the CS weight, the number of members in each group, and other factors. Net weights should be compared only within a group. Weights within a group are then normalized to yield the net weight. Normalization involves reducing the weight values while largely preserving the ratios between the weights. Normalization is performed within a group only if there is more than one available member in the group. Each group is calculated separately.

Result: In some cases, the value of NET WEIGHT is 1 (when the WLM WEIGHT or CS WEIGHT of all available members in the group is zero). This is done to force the load balancer to distribute workload in a round-robin fashion to those members rather than allowing the load balancer to potentially halt workload distribution to the entire group.

ABNORM

This field is displayed if the GROUP FLAGS values indicate that server-specific (SERVERWLM) WLM recommendations are being used. The value is nonzero if the server application is experiencing conditions in which transactions are completing abnormally. It represents a rate of abnormal transaction completions per 1000 total transaction completions. It is applicable only for target applications such as IWMRPT that act as Subsystem Work Managers and report transaction status using Workload Management Services. For example, the value 200 in this example indicates that 20% of all transactions processed by the server application are completing abnormally. Under normal conditions or if the server is not providing this information to WLM, this value should be 0.

A nonzero value indicates that the server application has reported some abnormal transaction completions to WLM and that WLM has reduced the server-specific recommendation for this server instance. The greater the value of this field, the greater the reduction in the recommendation provided by WLM. For more information about the conditions that cause the abnormal transaction completions for a given server application, see the documentation provided by the server application.

Restriction: Although WLM uses abnormal transaction completion rate information that is provided by the application to reduce the server-specific recommendation, this information is available for display on an Advisor only if the Load Balancing Agents and the Advisor are running on a z/OS V1R8 system or later. A z/OS V1R7 Load Balancing Agent does not provide this information to the Load Balancing Advisor. In this situation, a z/OS V1R8 Advisor shows a normal abnormal transaction completion rate of 0 even if WLM is reducing the server-specific recommendation because of a nonzero abnormal transaction completion rate reported from the application.

HEALTH

This field is displayed if the GROUP FLAGS values indicate that server-specific (SERVERWLM) WLM recommendations are being used. This health indicator is available only for applications that provide this information to WLM using the IWM4HLTH or IWMSRSRG services. It indicates the general health of an application or subsystem. Under normal circumstances or if the server is not providing this information to WLM, the value of this field is 100, indicating that the server is 100% healthy.

Values less than 100 indicate that the server is experiencing problem conditions that are not enabling it to process new work requests successfully; this causes WLM to reduce the server-specific recommendation for this server instance. The lower the value of this field, the greater the reduction in the recommendation provided by WLM.

Restriction: Although WLM uses the health indicator provided by the application to reduce the server-specific recommendation, this information is available for display on an Advisor only if the Load Balancing Agents and the Advisor are running on a z/OS V1R8 system or later. A z/OS V1R7 Load Balancing Agent does not provide this information to the Load Balancing Advisor. In this situation, a z/OS V1R8 Advisor shows a normal health indicator of 100 even if WLM is reducing the server-specific recommendation because of an abnormal health indication from the application.

FLAGS

Flag values that are currently set. Flag values are:

LBQ: Load Balancer quiesce, which means that the load balancer has requested that no more additional work be assigned to the quiesced application or system.
NOTARGETAPP: Indicates that an Agent found the IP address configured on a TCP/IP stack, but the Agent did not find a specific application using the same port and protocol.
NOTARGETIP: Indicates that an Agent found the IP address configured on a TCP/IP stack, but the address is not usable. For example, the IP address might be unavailable.
NOTARGETSYS: Indicates that no Agent found this IP address.
NODATA: Indicates that an Agent has reported this application but does not yet have the historical data to recommend a CS weight.
OPQ: Operator quiesce, which means that the MVS operator at the owning Agent has requested that no more additional work be assigned to the quiesced application or system.