IBM Support

IT27988: TPF Operations Server message processing enhancement

Subscribe to this APAR

By subscribing, you receive periodic emails alerting you to the status of the APAR, along with a link to the fix after it becomes available. You can track this item individually or track all items by product.

Notify me when this APAR changes.

Notify me when an APAR for this component changes.

 

APAR status

  • Closed as new function.

Error description

  • See Problem Summary.
    

Local fix

  • NA
    

Problem summary

  • APAR NUMBER:  IT27988
    PRODUCT:  TPF Operations Server Ver 1.2
    FUNCTIONAL AREA:  TPF OPERATIONS SERVER VER. 1.2
    SHIPPED IN VERSION:  1.2.0.6
    
    ABSTRACT:
    TPF Operations Server message processing enhancement
    
    PACKAGE CONTENTS:
    (C) include/etoscpp.h
    (C) TOSAuthUE/TOSAuthUE.h
    (C) TOSCryptUE/TOSCryptUE.h
    (C) API/lib/etoscpp.lib
    (C) bin/3270.dll
    (C) bin/CPPClient.exe
    (C) bin/etos.exe
    (C) bin/etoscpp.dll
    (C) bin/etosinternal.dll
    (C) bin/etosmessages.dll
    (C) bin/etosrexx.dll
    (C) bin/etossim.dll
    (C) bin/hmc.dll
    (C) bin/killtos.exe
    (C) bin/log2file.exe
    (C) bin/qtos.exe
    (C) bin/tos2tec.exe
    (C) bin/tostelnet.dll
    (C) com.ibm.tpf.tos64_1.2.6.jar
    (C) com.ibm.tpf.tos_1.2.6.jar
    (C) TOSApi64_1.2.6.jar
    (C) TOSApi_1.2.6.jar
    
    COMMENTS:
    Before this APAR, when the TPF Operations Server received
    messages from a z/TPF host interface (for example, 3215, 3270,
    and HMC), the messages were stored internally for each client
    (also known as a terminal address). The internal buffer was
    allocated with a default size of 128 KB per client after the
    terminal address (TA) session. The internal buffer could be
    changed by using the ETOSPIPESIZE environment variable; the
    valid range was in the range of 65536 (64 KB) - 6291456 (6 MB).
    
    However, the internal buffer sometimes got full if a client was
    slow to process the messages during high message traffic. The
    server waited for the slow client to remove the messages before
    the server added a new message to the internal buffer for that
    client. This caused delays when the server sent z/TPF messages
    to other clients and when the server read messages from the
    z/TPF host. The server might temporarily stop receiving
    messages from the host if the slow client could not process the
    messages. Eventually, the z/TPF system was unable to write
    messages to the TPF Operations Server and was forced to perform
    a console fallback.
    

Problem conclusion

  • SOLUTION:
    With this enhancement, the TPF Operations Server internal
    buffer can grow dynamically to handle the high message traffic
    and shrink when the memory is not needed. The buffer can grow
    to enable the server to store a burst of messages from the
    z/TPF system. This provides more time for the slow clients to
    process their messages, and can reduce the slowdown on other
    TPF Operations Server clients and the host interface.
    
    This APAR also introduces a new option for you to specify
    whether a terminal address (TA) is critical. The critical TAs
    are clients that must receive all of their messages, such as
    prime CRAS, message logging and automation (RAVEN), because
    losing any messages affects the daily operation. The
    noncritical TAs are the clients that can lose messages without
    impacting their operations. To define a TA as noncritical, add
    the statement "connection.criticalTA=false" in the session
    configuration file (.conf). If the statement
    "connection.criticalTA=true" is added or the
    connection.criticalTA option is omitted, the TA is critical.
    
    Although the new internal buffer can grow and shrink
    dynamically, there is a maximum memory capacity for each type
    of TA. The internal buffer for a critical TA can be set in the
    range of 10485760 (10 MB) - 104857600 (100 MB) by using the new
    environment variable ETOSCRITPIPESIZE. The default size of a
    critical TA buffer is 20 MB. The internal buffer for a
    noncritical TA can be set in the range of 65536 (64 KB) -
    6291456 (6 MB) by using the ETOSPIPESIZE environment variable.
    The default value of a noncritical TA buffer is 128 KB. All TPF
    Operations Server clients default to critical TAs after this
    APAR is installed. Each critical client can store host messages
    up to 20 MB. If the ETOSPIPESIZE environment variable is set
    currently, critical clients are not affected.
    
    When a noncritical TA buffer is full, the TPF Operations Server
    sends a warning to that client and drops the message. After the
    noncritical TA buffer size is below 25% of the ETOSPIPESIZE
    environment variable value, the TPF Operations Server resumes
    streaming the messages and indicates the number of messages
    that were dropped. If a critical TA buffer is full, the TPF
    Operations Server is blocked until its buffer is no longer
    full. The server also temporarily stops processing client and
    host messages. If this situation is prolonged, the z/TPF
    console might fall back.
    
    With the increase of the internal buffer size, the server
    memory usage can grow during high message traffic. Because the
    TPF Operations Server process has a 2 GB memory limit (32-bit),
    the new server calculates the maximum memory usage (number of
    critical TAs * ETOSCRITPIPESIZE + number of noncritical TAs *
    ETOSPIPSIZE) when a new TA session is established. If the
    calculated value is greater than 1.5 GB, a warning message is
    sent to all TAs to warn the operators that the server might run
    low in memory and crash. To alleviate this situation, each TPF
    Operations Server should manage one z/TPF host to enable more
    critical and noncritial TAs to connect.
    
    There is no code change to the TPF Operations Server host
    interface (3270.dll, hmc.dll, etossim.dll and tostelnet.dll).
    However, new messages (etosmessages.dll) were created for this
    enhancement, and those host DLLs were rebuilt to include the
    new message library. There is also no code change to the TPF
    Operations Server applications (CPPClient.exe, killtos.exe,
    log2file.exe, qtos.exe and tos2tec.exe). They were rebuilt to
    use the new connection.criticalTA option (etoscpp.lib).
    
    After you install this APAR, if you want to run your TPF
    Operations Server C++ or Java API programs as noncritical TAs
    (connection.criticalTA=false), recompile TPF Operations Server
    API programs (etoscpp.lib and TOSApi.jar). Otherwise, the
    current API programs run as critical TAs.
    
    COREQS: NO
    None.
    
    MIGRATION CONSIDERATIONS: YES
    Functional, automation, and operation changes:
    New messages:
    AAES4030W
    AAES4031I
    AAES4032W
    AAES4033W
    
    Application programming interface (API) changes:
    For C++ APIs:
    A new variable (bool criticalTA) is added to the
    TOSParameterBlock structure.
    The TOSParameterBlock structure is used for the TOS server
    connection.  The
    following TOS C++ APIs use that structure:
    
    ETOSClient:KillServer()  - Terminate the TOS server session
    ETOSClient:Open()        - Open the TOS server connection
    ETOSClient:Open()        - Open the TOS server connection with
    with retries
    ETOSClient:Open()        - Open the primary and fallback TOS
    server connections
    with retries
    ETOSClient:QueryServer() - Query the TOS server information
    
    The new option has no effect to KillServer() and QueryServer()
    APIs.
    
    For Java API:
    A new parameter is added in the CommunicationBlock() API.
    
    After the APAR is installed, all TOS clients are defaulted to
    be critical
    clients (terminal addresses), and there is no change to the C++
    and Java API
    programs.  Code updates are needed if you want an application
    to be a
    noncritical client.
    
    
    Before you apply this APAR to your system, ensure that TPF
    Operations Server version 1.2.06 or later is installed and
    the following APARs are applied in the following order:
    
    IC70878
    IC72531
    IT07558
    IT13849
    IT20282
    IT23451
    IT26830
    IT27175
    IT28903
    IT30897
    IT31881
    IT34521
    IT34114
    IT33558
    IT36459
    IT37161
    IT37609
    IT37767
    IT38621
    
    To maintain a list of APARs that are applied to your system,
    you can create a directory named "APAR" under the TPF
    Operations Server base directory, and keep all APAR text
    files (ICxxxxx.txt and ITxxxxx.txt) that are applied to your
    system as a log.
    
    To apply this APAR to your system, complete the following steps:
    1.  Fall back the z/TPF system.
    2.  Stop all clients
    3.  Stop the server
    4.  Unzip IT27988.zip to a temporary location.
    5.  Run "tosapar.bat".
    6.  Restart the server
    7.  Restart all client sessions.
    8.  Fall back the z/TPF system.
    
    After installing this APAR, if you want to run your TOS C++ or
    Java API
    programs as critical TAs (same as before), the TOS API programs
    do not need to
    recompile.  They run as critical clients by default.
    
    
    
    UPDATED INFORMATION UNITS: YES
    TPF Operations Server User's Guide
    
    See your IBM representative if you need additional information.
    
    DOWNLOAD INSTRUCTIONS:
    https://www.ibm.com/support/docview.wss?uid=swg27049608
    

Temporary fix

Comments

APAR Information

  • APAR number

    IT27988

  • Reported component name

    TPF OPS SRV W/2

  • Reported component ID

    5799GKX00

  • Reported release

    120

  • Status

    CLOSED PER

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt / Xsystem

  • Submitted date

    2019-02-05

  • Closed date

    2021-11-04

  • Last modified date

    2021-11-04

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

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

Publications Referenced
SK2T8062    

Fix information

  • Fixed component name

    TPF OPS SRV W/2

  • Fixed component ID

    5799GKX00

Applicable component levels

[{"Line of Business":{"code":"LOB35","label":"Mainframe SW"},"Business Unit":{"code":"BU058","label":"IBM Infrastructure w\/TPS"},"Product":{"code":"SSZL53","label":"TPF"},"Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"120"}]

Document Information

Modified date:
05 November 2021