OA52312: NEW FUNCTION - WLM SUPPORT FOR CONTAINER PRICING FOR IBM Z

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• New Function
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * All users of z/OS 2.2 (HBB77A0) and above.                   *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * NEW FUNCTION: WLM support for                                *
  * Container Pricing for IBM Z.                                 *
  *                                                              *
  * z/OS V2R2 and z/OS V2R3 WLM                                  *
  * introduces a new Tenant Resource                             *
  * Group capacity which allows the                              *
  * metering and optional capping of                             *
  * workloads, along with the ability to                         *
  * map those workloads directly to                              *
  * Container Pricing for IBM Z.                                 *
  *                                                              *
  * z/OS V2R1 WLM provides toleration and                        *
  * coexistence support which is required                        *
  * as soon as this new capability is                            *
  * exploited in a mixed release sysplex.                        *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  In order to support Container Pricing for IBM Z, WLM introduces
  Tenant Resource Groups which are similar to WLM resource groups
  but accept and process a 64-character Solution ID.
  
  A Pricing Container is composed of one or more Tenant Resource
  Groups that share a Solution ID.  The processor consumption of
  all address spaces and enclaves classified into a Tenant
  Resource Group is provided for metering capabilities including:
  - Rolling four-hour average of MSU
  - General purpose processor service units
  - Specialty engine service units
  
  Optionally, the processor consumption of a Tenant Resource
  Group can be capped by applying a maximum amount of processor
  capacity allowed to consume.
  
  SMFREC/K    PRICINGINFR/K
  

Problem conclusion

Temporary fix

Comments

• To define Tenant Resource Groups and exploit Container Pricing
  for IBM Z, the WLM Administrative Application is extended as
  follows:
  
  (1) Defining TENANT RESOURCE GROUPS (TRGs): Tenant resource
   groups allow the metering and optional capping of workloads,
   along with the ability to map those workloads directly to
   Container Pricing for IBM Z. A tenant resource group is
   comparable to a resource group but accepts and processes an
   IBM provided 64-character Solution ID. While a resource group
   is assigned to service classes, a tenant resource group is
   assigned to tenant report classes. When you specify a maximum
   capacity to the tenant resource group, WLM limits the amount
   of processor capacity available to work which is classified to
   the tenant report classes associated with the tenant resource
   group. You can define up to 32 tenant resource groups per
   service definition.
  
   Tenant resource groups are reported by WLM by the new IWM4QTNT
   (Query TRG consumption) service. This is the service reporting
   products should use to obtain the TRG's long-term average
   service on general purpose processors in millions of service
   units per hour and the TRG's service units consumed on general
   purpose processors and specialty engines since IPL or the last
   policy change. The information returned by IWM4QTNT is mapped
   by IWMWQTAA (Query TRG answer area).
  
  (2) Defining TENANT REPORT CLASSES (TRCs): Just as for report
   classes, classification rules can assign incoming work to a
   tenant report class. From the perspective of workload
   reporting services, tenant report classes are like normal
   report classes. However, tenant report classes are assigned
   to a tenant resource group and thus provide the metering
   capability for the tenant resource group. You can define up
   to 2047 tenant report classes per service definition whereby
   the sum of report classes and tenant report classes may not
   exceed 2047.
   When using tenant report classes in classification rules,
   note the following:
   + A tenant report class cannot be specified on a
     classification rule with a Reporting Attribute of MOBILE,
     CATEGORYA, or CATEGORYB. Workload management can report on
     processor consumption either based on tenant resource groups
     or based on special reporting options, but not both at the
     same time.
   + A classification rule cannot categorize work into a tenant
     report class and a service class which is associated with a
     resource group. Work cannot be subject to capping by means
     of resource groups and tenant resource groups at the same
     time.
   + As with report classes, tenant report classes are
     homogeneous or heterogeneous. WLM workload reporting
     services provide less meaningful data for heterogeneous
     than for homogeneous tenant report classes. Thus, it is
     recommended to define separate tenant report classes for
     each service class and assign them all to the same tenant
     resource group. If your tenant report class might become
     heterogeneous, the WLM ISPF applications displays an
     appropriate warning message.
  
   Tenant report classes are reported by WLM like report classes,
   for example, in the IWMRCOLL (Collect workload activity data)
   service.
  
  (3) Defining RESOURCE GROUPS: A new resource group type is
   supported when defining a guaranteed maximum and minimum CPU
   capacity. Besides unweighted CPU service units per second
   (Type 1), percentage of LPAR share (Type 2), and number of
   general purpose processors (Type 3), a new Type 4 is provided:
   Capacity in accounted workload MSU which is the processor
   consumption per hour expressed in million service units (MSU).
   While Type 2 and 3 have a system scope, Type 1 and new Type 4
   have a sysplex scope.
  
   Furthermore, a new option Include Specialty Processor
   Consumption can be defined: NO means that WLM management of
   the resource group is based only on general purpose processor
   consumption. This is the default. YES means that management of
   the resource group is based on general purpose and specialty
   processor total consumption.
  
   When defining the maximum capacity for tenant resource groups
   (TRGs), all 4 different types are available together with the
   Include Specialty Processor Consumption attribute.
  
  (4) Defining SERVICE DEFINITION OPTIONS: A new option is
   provided to deactivate WLM's discretionary goal management.
   Certain types of work, when overachieving their goals,
   potentially will have their general purpose processor
   resources "capped" in order to give discretionary work
   a better chance to run. Specifically, work that is not
   part of a resource group and has one of the following
   two types of goals will be eligible for this resource
   donation
   + A velocity goal of 30 or less
   + A response time goal of over one minute
   The default for Deactivate Discretionary Goal Management
   is NO, which enables this kind of resource donation. If
   you specify YES, you deactivate this kind of resource
   donation and workload management will not cap processor
   resources in order to help discretionary work.
  
  (5) WLM application and service definition functionality
   levels: With this function, the WLM Administrative Application
   level changes from 31 to 32. The WLM Administrative
   Application level 32 is only available with z/OS V2R2 and
   above when APAR OA52312 is applied.
  
   The functionality level of the WLM service definition changes
   to 32 as soon as
   - a tenant resource group is defined
   - a resource group is defined with capacity type 4
   - a resource group is defined with capacity type 2 and
     minimum or maximum capacity is greater than 99
   - a resource group is defined with option Include Specialty
     Processor Consumption
   - option Deactivate Discretionary Goal Management is defined
  
   This new functionality level 32 for WLM service definitions
   is introduced in mapping macros IWMSVAEA, IWMSVDCR, IWMSVDEF,
   IWMSVNPA, and IWMSVPOL.
  
   A WLM service definition with functionality level LEVEL032
   cannot be extracted, displayed, modified, installed or
   activated from a z/OS V2R1 or V2R2 or V2R3 system without
   APAR OA52312 applied. As soon as the functionality level of
   the WLM service definition increases to LEVEL032, all actions
   must be taken from a z/OS V2R2 or z/OS V2R3 system with
   APAR OA52312 applied.
  
   Once a functionality LEVEL032 service definition is installed
   and a policy is activated, it will run on all systems in a
   mixed release sysplex that have APAR OA52312 applied. However
   even with the APAR applied on a z/OS V2R1 system, tenant
   resource groups will be ignored and the new options will not
   be honored because the new functionality is tolerated but not
   exploited on z/OS V2R1. On systems without APAR OA52312
   applied, activation of a LEVEL032 policy will fail and the
   system will then run with the DEFAULT policy instead of the
   active policy if:
   - a resource group or tenant resource group is defined with
     capacity type 2 (percentage of LPAR share) and minimum or
     maximum capacity is greater than 99
   - a resource group or tenant resource group is defined with
     new capacity type 4 (accounted workload MSU)
  
  IMPORTANT NOTICES:
  
  (a) On systems with APAR OA52312 applied, the following
   inconsistency exists even if none of the new functions is
   used. The WLM service definition can be stored in ISPF tables,
   or in XML format. With this APAR structural changes to the
   ISPF tables are required. In that case, the WLM Administrative
   Application automatically updates the ISPF table structure
   when you save the service definition in ISPF table format,
   even if you do not exploit the new functionality. If this
   occurs, the saved service definition cannot be read by older
   levels of the WLM Administrative Application, or the IWMINSTL
   sample job. This problem does not exist if you save the
   updated service definition in XML format. Therefore, it is
   recommended to always use XML format when saving service
   definitions. If using ISPF table format, it is recommended
   to start updating a WLM service definition with a higher
   level of the WLM administrative application only when you are
   sure that you do not have to update that service defintion
   data set with a lower level of the WLM administrative
   application anymore.
  
  (b) The availability of the Container Pricing function can be
   obtained by invoking the REQSRMST SYSEVENT and checking the
   flag SRMSTWBG (see mapping macro IRASRMST).
  
  (c) Users of the z/OSMF WLM task must install the corresponding
   z/OSMF APAR PI89361 before exploiting this new function.
  
  For the collection of information about Container Pricing,
  please refer to:
  https://www.ibm.com/support/knowledgecenter/
  SSLTBW_2.3.0/com.ibm.zos.v2r3.izsc100/toc.htm
  
  For the Workload Management documentation updates related to
  this APAR, please refer to:
  http://publibz.boulder.ibm.com/zoslib/pdf/OA52312.pdf
  
  ---------------------------------------------------------------
  Doc updates for OA52312
  
  There are documentation updates for the following manuals:
  
  SC34-2662-XX z/OS MVS Planning: Workload Management
  SC34-2663-XX z/OS MVS Programming: Workload Management Services
  SA38-0667-XX z/OS MVS System Management Facilities (SMF)
  GA32-0936-XX z/OS MVS Data Areas Volume 2
  GA32-0937-XX z/OS MVS Data Areas Volume 3
  GA32-0904-XX z/OS MVS Diagnosis: Reference
  SA38-0666-XX z/OS MVS System Commands
  SC34-2662-XX z/OS MVS Planning: Workload Management
  
  ---------------------------------------------------------------
  
  
  SMFREC/K
  PRICINGINFR/K
  ×**** PE17/12/15 FIX IN ERROR. SEE APAR OA54590  FOR DESCRIPTION
  ×**** PE17/12/15 FIX IN ERROR. SEE APAR OA54590  FOR DESCRIPTION
  

APAR Information

• APAR is sysrouted FROM one or more of the following:

• APAR is sysrouted TO one or more of the following:

  UA94031 UA94032 UA94599

Modules/Macros

• IWMH8H   IWMHIX   IWMHIY   IWMAP1A  IRAPAINP IWMAR0B  IWMH8D
  IWMH5DF  IWMH5DD  IRAPAFST IWMH5DC  IWMI2L
  
  ***This field was truncated.  To obtain the full apar record, please contact your local support center.***
  

Fix information

• Fixed component name

  WORK LOAD MANAG

• Fixed component ID

  5752SCWLM

Applicable component levels

• R7B0 PSY UA94032

     UP17/12/13 P F712

• R7A0 PSY UA94031

     UP17/12/13 P F712

• R790 PSY UA94599

     UP17/12/13 P F712

Fix is available

• Select the PTF appropriate for your component level. You will be required to sign in. Distribution on physical media is not available in all countries.