IT27988: TPF Operations Server message processing enhancement

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 is sysrouted FROM one or more of the following:

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

Fix information

• Fixed component name

  TPF OPS SRV W/2

• Fixed component ID

  5799GKX00

Applicable component levels