OA53111: NEW FUNCTION - LOGGER STACK AFFINITY FOR IBM ZAWARE SERVER.

Obtain the fix for this APAR.

APAR status

• Closed as new function.

Error description

• Enhance system logger to allow use of a transport provider name
  for TCP/IP stack affinity in C-INET configurations when
  communicating to the IBM zAware server.
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED:                                              *
  * Users of HBB77A0 and above supported                         *
  * releases using System Logger Services and                    *
  * also exploiters of IBM System z Advanced                     *
  * Workload Analysis Reporter (IBM zAware).                     *
  ****************************************************************
  * PROBLEM DESCRIPTION:                                         *
  * Enhance system logger to support using                       *
  * a transport provider name for TCP/IP                         *
  * stack affinity for its communication                         *
  * with the IBM zAware server.                                  *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  IN SUPPORT OF NEW FUNCTION
  
  Enhance system logger to allow use of a transport provider name
  for TCP/IP stack affinity in C-INET configurations when
  communicating to the IBM zAware server.
  

Problem conclusion

Temporary fix

Comments

• IN SUPPORT OF NEW FUNCTION
  
  z/OS system logger has been enhanced to allow use of a transport
  provider name for TCP/IP stack affinity in C-INET configurations
  when communicating to the IBM zAware server.
  
  This PTF may be applied and activated on one system at a time in
  the sysplex.
  
  Systems with and without the fix activated can coexist in the
  same sysplex.
  
    Additional Searchable keywords:  SYSPLEXDS
     MSGIXG371E MSGIXG378I MSGIXG601I MSGIXG607I MSGIXG735I
  
  ENHANCEMENT Info FOR APAR OA53111
  z/OS system logger has been enhanced to allow use of a transport
  provider name for TCP/IP stack affinity in C-INET configurations
  when communicating to the IBM zAware server.
  
  This enhancement allows TPNAME(transport-name) to be specified
  on the z/OS system logger IXGCNFxx ZAI statement.  System logger
  will use the specified transport-name to set the affinity when
  establishing the IBM zAware socket communications.
  
  Refer to the documentation section for details on the logger
  changes.
  
  DOCUMENTATION Info FOR APAR OA53111
   z/OS Summary of Message and Interface Changes
     SYS1.PARMLIB member IXGCNFxx
      - ZAI statement has new TPNAME(transport-name) specification
  
     SYS1.SAMPLIB member IXGCNFXX
      - ZAI statement contains new default TPNAME(NONE)
     System Commands:
      - SETLOGR ZAI,TPNAME(transport-name)
     System Messages: (logger messages)
      changed logger messages:
      - IXG371E new error reason text
      - IXG601Iin response to Display LOGGER,IXGCNF ,ZAI
      - IXG607I will now include TPNAME value
      - IXG735I error reason text updated
      new logger message:
      - IXG378I when TCP/IP stack affinity is set
     APIs:
      - ENF48 signal- when TPNAME value changes
        to mapping macro IXGENF indicator IxgenfZAILocChg
      - IXGQUERY request=zailocinfo also returns
        tpname value
     - IXG378I  issued when TCP/IP stack affinity is set to the
       transport affinity name, TPNAME(value), or when the TCP/IP
       stack affinity has been removed, TPNAME(NONE)
  
   z/OS MVS Initialization and Tuning Reference
      +--- LOCATION IN PUBLICATION ----------------------------+
      +-- IXGCNFxx parmlib member, new ZAI statement keyword --+
  IXGCNFxx member-
   Specifying the IXGCNFxx members
  
   The following restrictions apply to the IXGCNFxx parmlib
   parameters when attempted to be updated as part of the SET
   IXGCNF=xx command processing.
  
   1.   ZAI SERVER, PORT, and TPNAME changes are not honored if
        there are existing socket connections to the IBM zAware
        server. Disconnect the applicable log streams or quiesce
        any existing socket connection through the SETLOGR
        FORCE,ZAIQUIESCE command (use the ALL keyword or LSN= for
        each applicable log stream).
  
   Syntax format of IXGCNFxx
     ZAI
      SERVER(NONE | host_name | IP_addr)
      PORT(port_num)
      TPNAME(NONE | transport_name)         < new parameter >
  
   Statements and parameters for IXGCNFxx
    ZAI
     TPNAME(NONE | transport_name)
       Optional parameter that specifies whether a transport
       provider name will be used by system logger to set the
       transport affinity, also called TCP/IP stack affinity,
       meaning sockets are restricted to just one transport
       provider for communications from the z/OS zAware log stream
       client to the zAware server.
  
       When the value NONE is specified for the TPNAME parameter,
       then no affinity to a specific transport provider will be
       used for establishing the sockets.
  
       When specified, the transport_name value must match a
       transport provider specified on the NAME parameter for a
       SUBFILESYSTYPE statement in BPXPRMxx or specified with the
       SETOMVS command.   Note that the transport provider name
       in this context refers to the TCP/IP address space name,
       which provides the functions also referred to as the
       "TCP/IP stack".   Refer to BPXPRMxx parmlib member and
       z/OS UNIX System Services Planning  for more details
       concerning transport providers.
  
       D LOGGER,IXGCNF,ZAI and D LOGGER,STatus,ZAI commands
       display the details on the system logger zAware log stream
       client information.
  
       Value range- Up to 8 alphanumeric or national ($, #, @)
       characters with the first character non-numeric; the
       system converts any lower case alphabetic characters to
       uppercase.
       Default- value NONE
  
   z/OS MVS System Commands
      +--- LOCATION IN PUBLICATION ----------------------------+
      +-- SETLOGR ZAI  command new parameter                 --+
  
   The parameters for SETLOGER ZAI are-
  
   Syntax-
    Table. SETLOGR MONITOR ZAI Command
    SETLOGR ZAI
     ,SERVER(NONE | host_name | IP_addr)
     ,PORT(port_num)
     ,TPNAME(NONE | transport_name)         < new parameter >
  
   Parameters-
    TPNAME(transport_name| NONE)
          << same as description on IXGCNFxx ZAI keyword >>
  
      ZAI SERVER, PORT and TPNAME changes are not honored if
      there are existing socket connections to the zAware server.
      Disconnect the applicable log streams or quiesce any
      existing socket connect(s) via the SETLOGR FORCE,ZAIQUIESCE
      command.
  
      D LOGGER,IXGCNF,ZAI and D LOGGER,STatus,ZAI commands
      display the details on the system logger z/OS IBM zAware
      log stream client information.
  
  
   z/OS MVS System Messages
      +--- LOCATION IN PUBLICATION ----------------------------+
      +--  changed Logger messages                           --+
      +--        IXG371E, IXG601I, IXG607I, IXG735I          --+
      +--  new     Logger message  IXG378I                   --+
  
   IXG371E ZAI LOGSTREAM CLIENT MANAGER UNAVAILABLE.
   REASON:  TCP/IP STACK AFFINITY (SETIBMOPT) FAILURE.
  
    Explanation-
     REASON-              < new reason >
      TCP/IP STACK AFFINITY (SETIBMOPT) FAILURE.
       Logger request to set the transport (TCP/IP) stack
       affinity (via SetIbmOpt) for the ZAI TPNAME value could
       not be satisfied since the name was either not configured
       or was not a Sockets physical file system (PFS).
  
    System programmer response-
     Do one of the following, depending on the text of this
     message-
     - When a transport (TCP/IP) stack affinity failure occurred,
       ensure the logger ZAI TPNAME value matches a correct
       SUBFILESYSTYPE statement in BPXPRMxx SYS1.PARMLIB member
       or specified with the SETOMVS command.
  
  
    Logger message IXG601I issued in response to
     Display LOGGER,IXGCNF ,ZAI  command
     can now include a quiesced reason when the TPNAME value
     results in an error when logger attempts to set the stack
     affinity, for example-
     D LOGGER,ST,ZAI
     IXG601I   14.26.26  LOGGER DISPLAY 112
     SYSTEM LOGGER STATUS
     SYSTEM   SYSTEM LOGGER STATUS
     ------   --------------------
     SY1      ACTIVE
  
     ZAI LOGSTREAM CLIENTS: QUIESCED      - STACK AFFINITY ERROR
     BUFFERS IN USE:   00 GB 0000 MB
  
  
    Logger message IXG607I (with ZAI options)
    will now include TPNAME(transport-name) as appropriate.
     For example-
     IXG607I hh:mm:ss LOGGER DISPLAY
     LOGGER            PARAMETER OPTIONS
     KEYWORD           SOURCE    VALUE
     ----------------- --------  ------------------------------
     ZAI
      SERVER           DEFAULT   NONE
      PORT             DEFAULT   2001
      TPNAME           DEFAULT   NONE
      LOGBUFMAX        DEFAULT   02
      LOGBUFWARN       DEFAULT   75
      LOGBUFFULL       DEFAULT   MSG
  
    Logger message IXG735I indicates when a logger configuration
    option (re: ixgcnfxx, setlogr, set ixgcnf=xx) has an error.
    There is more descriptive text with the ZAI SERVER CONNECTED
    reason.
     IXG735I LOGGER PARAMETER PROCESSING FAILED FOR request
     REASON: reason
  
     Explanation:
     reason
       One of the following:
       ZAI SERVER CONNECTED OR HAS LATENT ACTIVITY
  
   IXG378I ZAI LOGSTREAM CLIENT MANAGER IS USING TPNAME(tpname)
   TCP/IP STACK AFFINITY IS  NOW|NOT  IN EFFECT
  
    Explanation: System logger set the OMVS transport (TCP/IP)
    stack affinity to the value provided on the ZAI TPNAME
    parameter.  Logger used the OMVS BPX4PCT SetIbmOpt command
    request to assign the stack affinity for communications with
    the IBM zAware server.
    In the message text:
    tpname
         identifies the transport name specified on the logger
         configuration options ZAI TPNAME parameter.
         When the value is "NONE" then no transport (TCP/IP) stack
         affinity is currently being used.
    NOW  indicates logger is using TCP/IP stack affinity for the
         tpname value
    NOT  indicates logger is no longer using any TCP/IP stack
         affinity
  
    System action: The transport (TCP/IP) stack affinity value is
    used in establishing the IBM zAware server location, unless
    NONE was specified.
    Operator response: None
    System programmer response:  Verify the z/OS IBM zAware log
    stream client status is as expected using the
    D LOGGER,STatus,ZAI and D LOGGER,IXGCNF,ZAI commands.
  
  z/OS MVS Programming: Assembler Services Guide
   IXGQUERY: Get information about a log stream or system logger
     Use the IXGQUERY service to retrieve information about a log
     stream in the sysplex, or retrieve the system logger ZAI
   + SERVER, PORT, and TPNAME values pertaining to the z/OS IBM
     zAware server location.
     . . .
     When using the IXGQUERY service to retrieve system logger
     parameter options, the information is returned in a buffer
     mapped by IXGQZBUF. The information returned by IXGQUERY
     includes system logger parameter options for:
     v  ZAI SERVER value and significant length of value.
     v  ZAI PORT value and significant length of value.
   + v  ZAI TPNAME value and significant length of value.
   +    Refer to the IXGQZBUF mapping macro keyword
   +    IXGQZBUF_VERS=2 specification.
  
  z/OS MVS Programming: Assembler Services Reference IAR-XCT
   + IXGQUERY: Query a log stream or system logger for information
    REQUEST(ZAILOCINFO)
     The program requests to obtain information for the system
     logger ZAI parameter options pertaining to the IBM zAware
     server location.
     . . .
    ,BUFFLEN=bufflen
      A required input parameter that specifies the size of the
      buffer identified by the BUFFER64 keyword, relative to
      different output versions:
      v If the user-specified buffer is less than 96 bytes, the
        query request will fail and a specific return or reason
        code (IxgRetCodeError, IxgRsnCodeBadBufSize) will be
        returned.
      v If the user specified buffer is greater than or equal to
        96 bytes, then version one information will be returned.
        Meaning, the IXGQZBUF_Hdr fields will be filled in by
        logger with the following values:
   +    1.  IXGQZBUF_HDR_VER value is assigned a value of 1
   +        ('01'x)
   +    2.  IXGQZBUF_HDR_LEN value is assigned a value of 96
   +        ('60'x)
   +  v If the user specified buffer area length is greater than
   +    or equal to 128 bytes, then logger will return all the
   +    version 1 information and the version two information.
   +    The IXGQZBUF_Hdr fields will be filled in by logger with
   +    the following values:
   +    1.  IXGQZBUF_HDR_VER value is assigned a value of 2
   +        ('02'x)
   +    2.  IXGQZBUF_HDR_LEN value is assigned a value of 128
   +        ('80'x)
  
  z/OS MVS Data Areas Volume 3 (ITK - SCE)
    Mapping macro IXGQZBUF needs to be added to data areas book.
  
  OFFSET  OFFSET
  DECIMAL HEX   TYPE        LENGTH
  --------------------------------
     NAME (DIM)     DESCRIPTION
     --------------------------------
  96      (60)  CHARACTER   32
     IXGQZBUF_VERS2_SECTION_BEGIN(0)
                    Beginning of Version 2 section area
  96      (60)  CHARACTER   16
     IXGQZBUF_SERVERLOC2(0)
                    server location info - set 2
  96      (60)  CHARACTER   8
     IXGQZBUF_TPNAME
                    tpname value
  104     (68)  SIGNED      1
     IXGQZBUF_TPNAMELEN
                    number of significant characters for tpname
  

APAR Information

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

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

  UA93962 UA93963 UA93964 UA93965

Modules/Macros

• IXGXMSG  IXGLOGEN IXGWZASC IXGQZBUF IXGF1TTT IXGE1TPR IXGC4DIS
  IXGCNFXX IXGBLF01 IXGQUERY IXGP3DSP IXGP1DSP IXGC4CON IXGXENF
  IXGENF   IXGF2QRY IXGE1TLX IXGWZACC IXGF2WRT IXGE3CNF IXGE1CNF
  IXGLOGJP
  

Fix information

• Fixed component name

  SYSTEM LOGGER

• Fixed component ID

  5752SCLOG

Applicable component levels

• R7BJ PSY UA93963

     UP17/10/25 P F710  

• R7A0 PSY UA93964

     UP17/10/25 P F710  

• R7AJ PSY UA93965

     UP17/10/25 P F710  

• R7B0 PSY UA93962

     UP17/10/25 P F710  

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.