IBM Support

OA38747: System Logger enablement of z/OS IBM zAware log stream client

A fix is available

Subscribe

You can track all active APARs for this component.

 

APAR status

  • Closed as new function.

Error description

  • In Support of New Function
    
    In addition, this APAR will address the following MMS problem:
    When compiling SYS1.MSGENU(IXGLOGEN), the following error
    messages appear:
    
    CNLC117I PROCESSING DATA SET SYS1.MSGENU
    CNLC118I END OF INPUT REACHED
    CNLC173W LINE OR FORMAT NUMBER SPECIFIED FOR A UNIQUE MESSAGE
             ID, MESSAGE ID=IXG721I
    CNLC173W LINE OR FORMAT NUMBER SPECIFIED FOR A UNIQUE MESSAGE
             ID, MESSAGE ID=IXG733I
    CNLC100I MESSAGE COMPILER RUN COMPLETE, RC=04
    

Local fix

  • In SYS1.MSGENU(IXGLOGEN), the following two statements are in
    error:
    
    IXG721I   01001    SET IXGCNF COMMAND ACCEPTED
    IXG733I   01001    LOGGER PARAMETER PROCESSING UNAVAILABLE
    
    Remove the  01001  from both statements and the member will
    compile properly.
    

Problem summary

  • ****************************************************************
    * USERS AFFECTED: Users of HBB7780 and above supported         *
    *                 releases using System Logger Services        *
    *                 and log stream resources.                    *
    *                                                              *
    *                 And exploiters of IBM System z Advanced      *
    *                 Workload Analysis Reporter (IBM zAware) in   *
    *                 IBM zEnterprise EC12, zEC12.                 *
    *                                                              *
    *                      E2827/K                                 *
    ****************************************************************
    * PROBLEM DESCRIPTION: System Logger enablement of z/OS IBM    *
    *                      zAware log stream client                *
    *                      exploitation                            *
    *                                                              *
    ****************************************************************
    * RECOMMENDATION:                                              *
    ****************************************************************
    In SUPPORT OF NEW FUNCTION
    
    System Logger enablement of z/OS IBM zAware log stream client
    (zai logstream client).
    

Problem conclusion

Temporary fix

Comments

  • System logger has been enhanced to support z/OS as an IBM zAware
    monitored client.
    
    See the Enhancement and Documentation sections for details.
    
    The MMS errors described in the Error Description of this APAR
    were resolved by the PTFs for APAR OA38613.
    
    Activation of this enhancement on each system requires an IPL.
    
     Additional Searchable keywords:
       SYSPLEXDS
       IBM.Device.Server.zEC12-2827.Exploitation
    
    ACTION INFO FOR OA38747
    This enhancement may be applied to one system at a time in the
    sysplex.
    
    Systems with and without the enhancement activated can coexist
    in the same sysplex.
    
    System logger z/OS IBM zAware log stream client requirement -
    In order for z/OS to be a IBM zAware monitored client, System z
    Advanced Workload Analysis Reporter (IBM zAware) must be
    installed in a PR/SM logical partition (LPAR) in an IBM
    zEnterprise EC12 (zEC12) central processor complex (CPC) and
    accessible via z/OS Communication Server.
    
    Enablement of z/OS IBM zAware log stream client requires the
    PTFs for APAR OA38747, along with the underlying LPAR firmware
    support (identified above).  With this support, requested system
    logger actions will be performed in accordance with the IXGCNFxx
    parmlib member and log stream attribute specifications.  For
    more information, see z/OS MVS Setting Up a Sysplex.
    
    ENHANCEMENT INFO FOR OA38747
    z/OS system logger has been enhanced to support z/OS as an IBM
    zAware monitored client.  More specifically, this enhancement
    enables the z/OS IBM zAware log stream client support.
    
    The z/OS V1R13 publications refresh of the (on-line) soft copy
    in the z/OS product library contain the documentation updates
    for the enhancements described in APAR OA38747.
    
    The z/OS V1R13 refresh is available in the z/OS Internet Library
    (URL) web site at http://www.ibm.com/systems/z/os/zos/bkserv/.
    
    Also see the Documentation section in this PTF cover letter for
    more details; as any exceptions for the most current
    documentation are identified.
    
    Enhancement summary -
    z/OS provides the capability of having specific log stream data
    sent "out-of-band" to the System z Advanced Workload Analysis
    Reporter ( IBM zAware) firmware.  IBM zAware is described in the
    IBM System z Advanced Workload Analysis Reporter (IBM zAware)
    Guide. An instance of the IBM zAware firmware runs in a PR/SM
    logical partition (LPAR) in an IBM zEnterprise EC12 (zEC12)
    central processor complex (CPC).
    
    From a z/OS perspective, the z/OS images communicating with an
    IBM zAware firmware are identified as z/OS IBM zAware clients,
    and the IBM zAware firmware is identified as the IBM zAware
    server. The IBM zAware server will monitor/manage the z/OS
    images within its scope.
    
    For z/OS, the initial data being sent to the IBM zAware server
    for analysis is the log data within the OPERLOG log stream,
    which is called a z/OS IBM zAware log stream client. This allows
    the IBM zAware server to provide analytical monitoring and
    machine learning of z/OS health for purposes of availability
    management
    
    By default, z/OS will not communicate with the IBM zAware server
    unless the z/OS IBM zAware log stream client requirements are
    established as follows:
    
    1. Specify the ZAI parameters for the z/OS IBM zAware log stream
       client socket communication and log data buffering details in
       order to send log stream data to the IBM zAware server that
       will receive and process data from this z/OS image.  Refer to
       the system logger SYS1.PARMLIB member IXGCNFxx in z/OS MVS
       Initialization and Tuning Reference.
    
    2. The IXGLOGR address space must have security permission for a
       z/OS UNIX System Service segment. The z/OS UNIX System
       Service segment is only for TCP/IP connectivity. UID(0) or
       super user ability can be used but are not required. For
       example, in RACF issue the following command(s):
    
        ADDUSER IXGLOGR OMVS(UID(xxxx) HOME( / ))
        or
        ADDGROUP IXGGRP OMVS(GID(yyyy))
        ADDUSER IXGLOGR DFLTGRP(IXGGRP) OMVS(UID(xxxx) HOME( /tmp )
          PROGRAM( /bin/false )) NOPASSWORD
    
       where xxxx is a unique user id and yyyy is a unique group id.
    
    3. The z/OS Communications Server environment must be available,
       meaning the z/OS UNIX System Services (OMVS) and resolver
       address spaces, VTAM address space and appropriate TCP/IP
       address space have been started.  Also the necessary TCP/IP
       (network) definitions provided for the server location to be
       determined in order for logger to establish a (socket)
       connection to the IBM zAware server. See z/OS Communications
       Server IP Configuration Guide and z/OS UNIX System Services
       Planning for additional details for establishing the desired
       environment.
    
    4. The appropriate log streams have the ZAI related keywords
       specified for the intended log stream data to be sent to the
       IBM zAware server. For example, use the ZAI(YES)
       ZAIDATA('OPERLOG') parameter spcifications for the SYSPLEX
       OPERLOG log stream for OPERLOG log data to be sent to the IBM
       zAware server. If the Security Authorization Facility (SAF)
       is available, SAF update access to the RESOURCE
       (IXGZAWARE_CLIENT) in class CLASS(FACILITY) is required for
       the ZAI(YES) log stream specification.
    
       It is important to note that any log streams defined using
       the LIKE(SYSPLEX.OPERLOG) specification will pick up the ZAI
       and ZAIDATA setting from the SYSPLEX.OPERLOG log stream
       definition. Care needs to be taken by the installation to
       ensure these other log streams do not have the ZAI(YES)
       designation, unless that is the absolute intention.
    
    5. When a log stream connection exists on the z/OS image for the
       appropriate log stream, and the above conditions have been
       met, system logger will establish z/OS IBM zAware log stream
       client (socket) connection and send the log data to the
       appropriate IBM zAware server.
    
    System Logger uses "ZAI LOGSTREAM CLIENT" in message text to see
    "z/OS IBM zAware log stream client" activity.
    
    If the IBM zAware server is not available for a short period
    (for example, if it has been deactivated for maintenance), the
    BPX-services that system logger uses to send data will fail with
    error return codes.  The system logger will discover that either
    the socket connection is lost or after a number of retries on
    sending data that continue to fail, logger will disconnect from
    the socket explicitly.  System logger will then re-attempt a new
    socket connection with the IBM zAware server.  If the connection
    succeeds, logger will continue sending written OPERLOG messages
    to the IBM zAware server.
    
    If the re-attempt to connect to the server does not succeed,
    then the z/OS IBM zAware log stream client is considered in a
    quiesced state.  This means that any OPERLOG messages that were
    buffered for the purpose of sending to the IBM zAware server
    will be tossed and any newly written OPERLOG message will not be
    buffered.  After the IBM zAware server is made available again,
    z/OS system logger provides a SETLOGR
    FORCE,ZAICONN,LSN=SYSPLEX.OPERLOG command to cause logger to
    establish a socket connection with the IBM zAware server.  If
    this connection succeeds, logger will start sending newly
    written OPERLOG messages to the IBM zAware server.
    
    
    DOCUMENTATION INFO FOR OA38747
    Summary of changed Publications --
      z/OS V1R13 MVS Planning For Installation     GA22750423
      z/OS V1R13 MVS Planning:  Operations         SA22760113
      z/OS V1R13 MVS Setting Up a Sysplex          SA22760514
      z/OS V1R13 MVS Initialization and            SA22759222
                     Tuning Reference
      z/OS V1R13 MVS Programming: Assembler        SA22760113
                     Services Reference,
                     Vol 2 (IARR2V - XCTLX)
      z/OS V1R13 MVS Programming: Assembler        SA22760514
                     Services Guide
      z/OS V1R13 MVS Programming: Authorized       SA22760816
                     Assembler Services Guide
      z/OS V1R13 MVS System Commands               SA22762726
      z/OS V1R13 MVS System Management Facilities  SA22763024
                     (SMF)
      z/OS V1R13 MVS System Messages,              SA22764024
                     Vol 10 (IXC-IZP)
      z/OS V1R13 MVS Diagnosis: Reference          GA22758816
    
    The z/OS V1R13 publications refresh of the (on-line) soft copy
    in the z/OS product library contain the complete documentation
    updates for the enhancements outlined below.
    
    The z/OS V1R13 refresh is available in the z/OS Internet Library
    (URL) web site at http://www.ibm.com/systems/z/os/zos/bkserv/.
    
    Any exceptions for the most current documentation are identified
    below after section Documentation exceptions,
    refer to tag < Refresh exception- >.
    
    
    Documentation summary -
    ---------------------
    z/OS V1R13 MVS Planning For Installation
      - in appendix C. Hardware requirements for running z/OS V1R13
        added to BCP element - requirement to install IBM zAware
        firmware on IBM zEnterprise EC12 (zEC12) in order to have
        z/OS be an IBM zAware monitored client.
    
    z/OS V1R13 MVS Planning:  Operations
      - in chapter 5  Planning for Operation Tasks added new topic
        Exploiting the IBM System z Advanced Workload Analysis
        Reporter (IBM zAware) for OPERLOG
    
    z/OS V1R13 MVS Setting Up a Sysplex
      - updates in topic Planning the IXGCNF system parameter
    
      - in chapter 9  Planning for System Logger Applications
        add new topic -
        Preparing for z/OS IBM zAware log stream client usage
    
      - define authorization for IXGLOGR address space to USS
        services
    
      - DEFINE LOGSTREAM NAME(name)
                 ZAI({NO | YES | NO_ZAI})
                 ZAIDATA({'NO_ZAIDATA' | 'string'})
    
      - UPDATE LOGSTREAM NAME(name)
                 ZAI({NO_ZAI | NO | YES})
                 ZAIDATA({'NO_ZAIDATA' | 'string'})
    
      - plus update topic on when dynamic updates take effect
    
    z/OS V1R13 MVS Initialization and Tuning Reference
      - IXGCNFxx sys1.parmlib member new parms
         + ZAI
         +   SERVER(NONE | host_name | IP_addr)
         +   PORT(port_num)
         +   LOGBUFMAX(value)
         +   LOGBUFWARN(nn)
         +   LOGBUFFULL(MSG|QUIESCE)
    
    z/OS V1R13 MVS Programming: Assembler Services Reference,
         Vol 2 (IARR2V - XCTLX)
      - IXGINVNT
         - DEFINE LOGSTREAM NAME(name)
           +       ,ZAI={NO | YES | NO_ZAI}
           +       ,ZAIDATA={NO_ZAIDATA | string}
         - UPDATE LOGSTREAM NAME(name)
           +       ,ZAI={NO_ZAI | NO | YES}
           +       ,ZAIDATA={NO_ZAIDATA | string}
         - Reason Code '80D'x (IXGRSNCODENOSAFAUTH)
    
      - IXGQUERY
        +  REQUEST=ZAILOCINFO
        +        ,BUFFER64=xbuffer64
        +        ,BUFFLEN=xbufflen
    
    z/OS V1R13 MVS Assembler Services Guide
      - Updating a log stream's attributes
        < See Setting Up a Sysplex ZAI and ZAIDATA descriptions. >
    
    z/OS V1R13 MVS Programming: Authorized Assembler Services Guide
      - Writing an ENF event 48 listen exit
        New ENF 48 signal indicator in IXGENF mapping.
    
    z/OS V1R13 MVS System Commands
      - D Logger ...ZAI options
    
         D LOGGER,{STATUS|ST}
                            ,{RECALLS|REC}
        +                   ,{ZAI}
        +                        ,VERIFY
                 ,{IXGCNF}
                         ,{MONITOR|MON}}
        +                ,{ZAI}
                 ,{CONNECTION|CONN|C}
                                    ,LSNAME|LSN=logstreamname
                                    ,JOBNAME|JOB|J=mvsjobname
                                    ,SUMM|S
                                    ,DETAIL|D
                                    ,SYSPLEX,LSNAME=lsname
                                    ,DASDONLY
        +                           ,ZAI
                 ,{LOGSTREAM|L}
                              ,LSNAME=logstreamname
                              ,STRNAME|STRN=structurename
                              ,DASDONLY
        +                     ,ZAI
                 ,{STRUCTURE|STR}
                                ,STRNAME|STRN=structurename
                 ,L={a|name|name-a}
    
      - SET IXGCNF=xx or   T IXGCNF=xx
         - make use of zAI value and other keywords
    
      - SETLOGR
           FORCE (new keywords)
             ,{ZAIQUIESCE | ZAIQUI | ZAICONNECT | ZAICONN}
                 ,{LSN | LSNNAME}=LogStreamName | ALL } }
    
      + SETLOGR  (new option and keywords)
           ZAI
             {,SERVER(NONE | host_name | IP_addr) }
             {,PORT(port_num) }
             {,LOGBUFMAX(value) }
             {,LOGBUFWARN(nn) }
             {,LOGBUFFULL(MSG|QUIESCE) }
    
    z/OS V1R13 MVS System Management Facilities (SMF)
      - SMF88 record update
    
    z/OS V1R13 MVS System Messages, Vol 10 (IXC-IZP)
      - new system logger messages (range IXG37x thru IXG38x)
    
    z/OS V1R13 MVS Diagnosis: Reference
      - System Logger chapter
        - Utility IXCMIAPU data type(logr) output to include new
          system logger log stream specifications
    
        - new topic:
          Resolving system logger z/OS IBM zAware log stream
          client errors
    &#215;**** AE13/01/30 FIX IN ERROR. SEE APAR OA41313  FOR DESCRIPTION
    

APAR Information

  • APAR number

    OA38747

  • Reported component name

    SYSTEM LOGGER

  • Reported component ID

    5752SCLOG

  • Reported release

    780

  • Status

    CLOSED UR1

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    YesSpecatt / New Function / SYSPLXDS /

  •  

    Xsystem

  • Submitted date

    2012-02-08

  • Closed date

    2012-08-30

  • Last modified date

    2013-07-30

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

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

    UA66495 UA66494

Modules/Macros

  • IXGBLF01 IXGCNFXX IXGCON   IXGENF   IXGE3CNF
    IXGF1TTT IXGF2QRY IXGILSAB IXGINVNT IXGIPFMT IXGIPRQE IXGIPVTC
    IXGLOGEN IXGLOGJP IXGMLSAB IXGMPVTC IXGM1TSK IXGP1DSP IXGQUERY
    IXGQZBUF IXGSMF88 IXGWZACC IXGWZASC IXGXENF  IXGXMSG
    

Publications Referenced
GA22750423SA22760113SA22760514SA22759222SA22760113
SA22760514SA22762726SA22763024SA22764024GA22758816
SA22760816    

Fix information

  • Fixed component name

    SYSTEM LOGGER

  • Fixed component ID

    5752SCLOG

Applicable component levels

  • R78J PSY UA66495

       UP12/09/19 P F209

  • R780 PSY UA66494

       UP12/09/19 P F209

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.

[{"Business Unit":{"code":"BU011","label":"Systems - zSystems software"}, "Product":{"code":"SG19M","label":"APARs - z/OS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"780","Edition":""},{"Business Unit":{"code":"BU011","label":"Systems - zSystems software"}, "Product":{"code":"SG19O","label":"APARs - MVS environment"},"Component":"","ARM Category":[],"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"780","Edition":""}]

Document Information

Modified date:
30 July 2013