IWMSRSRS macro — Sysplex Routing Information

IWMSRSRS provides three functions: SELECT, QUERY and SPECIFIC. All return a list of registered servers known to the system on which the service is invoked. Servers which have deregistered, via IWMSRDRS, may still be present in the output list, due to the asynchronous nature of deregistration. Conversely, some registered servers may not appear for this same reason.

When either the SELECT or the SPECIFIC function is chosen, IWMSRSRS will return a list of servers in the sysplex which are associated with the input Location name along with a relative weighting for each server. These servers are identified by their Network id and LU name, which were previously registered using the Sysplex Router Register macro, IWMSRSRG. Note that some servers may not appear in the output list due to balancing decisions, so this service should not be used as a general query service to find all currently registered servers for the input location.

Next to each server in the list will be a weight which tells the caller the relative number of requests to send to each entry. For example, the caller might send the indicated number of requests to each LU in the list before routing to the next LU in the list.

Server            Weight    CPU Weight    zAAP Weight    zIIP Weight
------            ------    ----------    -----------    -----------
NETIDA.LUNAME1       4           3              6              4
NETIDB.LUNAME2       7           8              3              9
NETIDC.LUNAME3       1           3              1              0
NETIDD.LUNAME43      4           5              2              3
NETID4.LUNAME2       2           1              2              2

The requestor could then choose to send the first 4 requests to NETIDA.LUNAME1, the next 7 requests to NETIDB.LUNAME2, the next request to NETIDC.LUNAME3, and so forth. When the list is exhausted, the requestor could invoke this macro again and get a whole new list or could rotate through the list again. It is expected that the requestor would invoke this macro frequently to get current system views for work balancing. For example, it would be appropriate for the caller to invoke this service approximately every 1 to 3 minutes, so that the list will remain current with changing system conditions and server availability.

Starting with z/OS V1R9, three new output weights are available: the CPU weight, the zAAP weight and the zIIP weight. The CPU weight is computed the same way as the weight was prior to V1R9, taking only CPU data into account. The zAAP and the zIIP weights are computed when taking only zAAP, respectively zIIP, data into account. The weight is a combination of these three processor weights.

Starting with z/OS V1R11, an optional input keyword METHOD selects how the weight (also referred to as "mixed" weight) is computed. The default is METHOD=PROPORTIONAL, which calculates the weight as a combination of these 3 processor weights (CPU, zAAP and zIIP). It is the same method as prior to V1R11. With METHOD=EQUICPU, WLM computes the weight by trying to simulate a 100% usage of the system capacity, and determining the capacity of a CPU-only system having equivalent resource consumption.

Both methods can be specified with keyword IL_WEIGHTING, and EQUICPU by COST_ZAAP_ON_CP and COST_ZIIP_ON_CP too.

The QUERY function is only available on systems running OS/390 R3 or higher. When the QUERY function is requested, IWMSRSRS will return the list of all servers in the sysplex which are associated with the input Location name along with a fixed weight of one for each server. The format of the output is the same as for SELECT.

When using the QUERY function, the CPU, zAAP and zIIP weights are always set to 0.

When using the SELECT or the SPECIFIC function, the mixed weight is a combination of the CPU, zAAP and zIIP weights with the relative use of the CPU, zAAP and zIIP by the server. Moreover, the mixed weights are scaled up, so that their sum is 64. Due to rounding errors, the sum of the mixed weights is usually as low as 64-(number of servers).

If there are pre-V1R9 systems in the sysplex, the zAAP and zIIP weights are automatically set to 0, and the weight is equal to the CPU weight, because pre-V1R9 systems do not have such weights and could not be correctly compared to V1R9 systems.

The Sysplex Routing Service (IWMSRSRS) can be used to obtain the userdata associated with each server when invoked on a system at OS/390 R3 or higher, though servers resident on an earlier release will be associated with userdata which is binary zeroes.

The SPECIFIC function is available on systems running z/OS R7 or higher. When the SPECIFIC function is issued, IWMSRSRS returns a list of servers in the sysplex which are associated with the input Location name along with a relative weighting for each server. In contrast to the weights in the SELECT function, the weights in the SPECIFIC function do not only consider available capacity values and the number of servers on the same system.

With the SPECIFIC function the following three additional factors are taken into account:

- The performance index that indicates the achievement of the WLM defined goals of the server, that is its related work. A server that achieves its goal is preferred over one that does not achieve its goal.

- If the server owns independant enclaves those also take the delays into account that the work is subject to, due to the queue times of the owned enclaves. A server with less average queue times for its enclaves is preferred over one with higher queue times.

- The health factor of this server. It is dependent on the health indicator which was reported to WLM for this server by the IWM4HLTH service or by IWMSRSRG. If no health indicator was reported, this factor is also neutral. This factor is only taken into account on systems running z/OS V1R7 with OA14310 installed, and on systems running z/OS V1R8 or higher.