PK64875: EYUCL0107E OR OTHER MAS CONNECTION FAILURE MESSAGE IF PREVIOUS RUN OF MAS DID NOT GET CLEANED UP

Obtain the fix for this APAR.

APAR status

• Closed as program error.

Error description

• If a MAS terminates, but CPSM termination routines are not given
  a chance to clean up properly, the next run of the MAS may not
  be able to connect to the ESSS address space.
  Additional Symptom(s) Search Keyword(s):
  KIXREVRJL
  

Local fix

Problem summary

• ****************************************************************
  * USERS AFFECTED: All CICSPlex/SM V3R1M0 Users                 *
  ****************************************************************
  * PROBLEM DESCRIPTION: Unpredictable results may occur if a    *
  *                      MAS terminates as a CICS system but     *
  *                      does not disconnect from the ESSS.      *
  ****************************************************************
  * RECOMMENDATION: If the CPSM environment contains CMASes and  *
  *                 MASes at both the CPSM V3R1M0 and V3R2M0     *
  *                 levels, then before applying the PTF that    *
  *                 resolves this APAR and restarting V3R1M0     *
  *                 CMASes and MASes, the PTF that resolves APAR *
  *                 PK64919 must be applied to the V3R2M0 CMASes *
  *                 and MASes.                                   *
  *                                                              *
  *                 After applying the PTF that resolves this    *
  *                 APAR, all CMASes, MASes and WUI servers must *
  *                 be restarted with the updated code.          *
  *                                                              *
  *                 The restarts need not be performed at the    *
  *                 same time, however if systems are not        *
  *                 restarted at the same time, the following    *
  *                 rules apply:                                 *
  *                                                              *
  *                 - Maintenance point CMASes must be restarted *
  *                   before non Maintenance point CMASes, MASes *
  *                   and WUI Servers.                           *
  *                                                              *
  *                   If you have more than one Maintenance      *
  *                   point CMAS and those Maintenance point     *
  *                   CMASes are connected directly or           *
  *                   indirectly, then those maintenance point   *
  *                   CMASes must be restarted at the same time. *
  *                                                              *
  *                 - Before a MAS or WUI server is restarted,   *
  *                   the CMAS to which the MAS or WUI server    *
  *                   connects must be restarted.                *
  *                                                              *
  *                                                              *
  *                 To restart with the updated code, the CPSM   *
  *                 Environment Service System Services (ESSS)   *
  *                 subsystem address space (EYUX310) must be    *
  *                 terminated and the CPSM EYUX subsystem End   *
  *                 of Task (EOT) exit (EYU9XEET) must be        *
  *                 reloaded on the MVS image if a CMAS has      *
  *                 executed without the updated code since the  *
  *                 last IPL.                                    *
  *                                                              *
  *                 This can be accomplished in either of two    *
  *                 ways:                                        *
  *                                                              *
  *                   1 - IPL the MVS Image.  This terminates    *
  *                       the ESSS and the EYUX subsystem.  When *
  *                       the first CMAS starts after the IPL,   *
  *                       the ESSS address space and the EYUX    *
  *                       subsystem will be started at the       *
  *                       proper level.                          *
  *                                                              *
  *                 Or:                                          *
  *                                                              *
  *                   2 - Stop all CMASes and MASes on an MVS    *
  *                       image.                                 *
  *                                                              *
  *                     - Use EYU9XENF to check that no address  *
  *                       spaces are connected to the ESSS       *
  *                       subsystem.                             *
  *                                                              *
  *                     - Use the EYU9XEUT TERMINATE function to *
  *                       stop the ESSS.                         *
  *                                                              *
  *                     - Use the EYU9XEUT RELOAD function with  *
  *                       the EOT option to reload EYU9XEET,     *
  *                       ensuring that UTILLIB specifies the    *
  *                       SEYUAUTH library updated by the PTF.   *
  *                                                              *
  *                     - Refresh LLA to ensure the updated      *
  *                       version of EYU9X310 is picked up.      *
  *                                                              *
  *                     - Restart any CMASes, MASes, and WUI     *
  *                       servers which execute on the MVS       *
  *                       image, ensuring that the updated       *
  *                       libraries are being picked up.  When   *
  *                       the first CMAS is started the ESSS     *
  *                       address space will be started at the   *
  *                       proper level.                          *
  *                                                              *
  *                 For details on EYU9XENF and the EYU9XEUT     *
  *                 TERMINATE and RELOAD functions, please refer *
  *                 to "CICS Transaction Server for z/OS         *
  *                 CICSPlex SM Problem Determination Guide      *
  *                 Version 3 Release 1" (GC34-6472).            *
  *                                                              *
  *                 Note that each MVS image can be updated      *
  *                 separately, and systems on an MVS image that *
  *                 have been updated can communicate with       *
  *                 systems on other MVS images that have not    *
  *                 been updated without problem.                *
  ****************************************************************
  When a CPSM CMAS or MAS (including WUI servers) address space
  terminates abnormally without going through ESSS termination
  (e.g, CANCEL), the Subsystem Interface End of Task (EOT)
  processing will drive CPSM's EYUX subsystem router exit,
  EYU9XEER, to perform termination.  After verifying that the
  address space is still connected to the ESSS, EYU9XEER will pass
  control to the EYUX subsystem EOT module EYU9XEET, which will
  issue the ESSS terminate request. If the terminate request was
  successful, EYU9XEET will issue message EYUXE0003I.  Otherwise,
  it will issue message EYUXE0029E.  If the processing is not
  successful, this can result in the address space terminating but
  still being connected to the ESSS.  This can result in the
  errors documented above.
  
  Both EYU9XEER and EYU9XEET must obtain working storage to
  process.  If the address space termination was caused by short
  of storage related problems, it is entirely possible that either
  or both EYU9XEER and EYU9XEET will not be able to obtain the
  required storage, thus ensuring that the ESSS termination
  request will not be performed.  While EYU9XEER will issue
  message EYUXE0030E if it cannot obtain its working storage,
  EYU9XEET does not issue any message.
  

Problem conclusion

• To address EYU9XEER and EYU9XEET not being able to run due to
  storage constraint in the address space at abnormal termination,
  CMAS and MAS ESSS connect processing has been updated to
  allocate working storage for both EYU9XEER and EYU9XEET.  If the
  address space goes through normal ESSS termination (address
  space termination or termination of the MAS agent in the MAS),
  ESSS termination processing will free the storage.  If the
  address space does not go through normal termination, EYU9XEER
  and EYU9XEET will be called and will use the pre-allocated
  storage.  When EYU9XEER and EYU9XEET complete processing, the
  TCB will terminate, and the pre-allocated storage will be freed
  at that time.
  
  The following updates have been made to effect this change:
  
  -  copybook EYURXECB, which is the ESSS anchor block for the
     system, has been updated to include fields to hold the
     address and length of the pre-allocated storage areas for
     EYU9XEER and EYU9XEET.
  
  -  copybooks EYURXEER and EYURXEET have been created to map the
     working storage areas for EYU9XEER and EYU9XEET.
  
  -  macro EYUQXESV, which is used to define and pass control to
     the ESSS PC routines common service subroutines, has been
     updated to define two new subroutines, ACQ_SSIDSA and
     REL_SSIDSA.
  
  -  copy book EYU2XERT, which is included in the assembly of the
     CPSM PC routines module EYUTXEPC, and which houses the common
     service subroutines for the PC routines, has been updated to
     include the new ACQ_SSIDSA and REL_SSIDSA subroutines:
  
     -  ACQ_SSIDSA will allocate the working storage for EYU9XEER
        and EYU9XEET, anchoring the storage in the EYURXECB.
  
     -  REL_SSIDSA will release the storage and clear the pointers
        in the EYURXECB.
  
  -  copy book EYU2XEEC, which is included in the assembly of the
     CPSM PC routines module EYUTXEPC, and which houses the ESSS
     connect processing, has been updated to call ACQ_SSIDSA when
     the connect request is for a CMAS or MAS.
  
  -  copy book EYU2XEET, which is included in the assembly of the
     CPSM PC routines module EYUTXEPC, and which houses the ESSS
     terminate processing, has been updated to call REL_SSIDSA
     when the terminate request is for a CMAS or MAS, and was not
     originated by EOT processing.
  
  -  module EYU9XEER has been updated to check the associated
     EYURXECB for a pre-allocated storage area if it is called
     for EOT of the QR TCB in a CMAS or MAS.  If the area is
     present and large enough, EYU9XEER will use the provided
     storage instead of allocating the storage itself.  On
     termination, EYU9XEER will not attempt to free the storage,
     as it will be freed when the QR TCB terminates.
  
  -  module EYU9XEET has been updated to check the associated
     EYURXECB for a pre-allocated storage area if it is called
     for EOT of the QR TCB in a CMAS or MAS. If the area is
     present and large enough, EYU9XEET will use the provided
     storage instead of allocating the storage itself.  On
     termination, EYU9XEET will not attempt to free the storage,
     as it will be freed when the QR TCB terminates.
  
     If no storage pointer is present in the EYURXECB or EYU9XEET
     cannot use the storage, or if the EOT call is not for the
     CMAS or MAS QR TCB, then EYU9XEET will allocate the storage
     itself.  If a failure occurs during the allocation attempt,
     EYU9XEET will now issue new message EYUXE0037E before
     terminating.  The text of this new message is as follows:
  
       EYUXE0037E  Insufficient storage for Subsystem function
                   End Of Task (EOT).
  
  
  To address a MAS terminating as a CICS system without
  disconnecting from the ESSS, a new action, FORCEDISCON, is being
  added to the MAS resource table.  Issuing the FORCEDISCON action
  against a MAS will cause the ESSS termination process to be
  driven for the MAS.  It is the intention that this action will
  only be issued if the MAS did terminate as a CICS system but is
  still connected to the ESSS.  If this command is issued for an
  active MAS, unpredictable results will occur, that will most
  likely make the MAS unusable as a CICS system.  To try to avoid
  this from occurring, a second new action, STOPUNCON, is also
  being added to the MAS resource table.  This action will process
  similar to STOP, in that it will stop the MAS agent in the MAS,
  which includes ESSS disconnect, without terminating the MAS as a
  CICS system.  STOPUNCON differs from STOP in two manners:
  
  1.  While the STOP action is issued synchronously, the STOPUNCON
      action is issued asynchronously.  This to ensure that the
      requester will not hang if the MAS is active and
      non-responsive or if the MAS terminated as a CICS system but
      is still connected to the ESSS.
  
  2.  While the STOP function will only terminate the MAS agent if
      the MAS is not a CPSM WLM routing region, the STOPUNCON will
      always terminate the MAS agent if the MAS is responsive.
  
  In order to issue the FORCEDISCON action, the STOPUNCON action
  must be issued first and not succeed in terminating the MAS
  agent.
  
  The following updates have been made to effect this change:
  
  -  the Topology CICS System Descriptor Block (EYURTISD) has been
     updated to include a flag setting to indicate whether a
     STOPUNCON action has been issued for the current execution of
     the MAS.
  
  -  the MAS resource table has been updated to add the two new
     actions, STOPUNCON and FORCEDISCON.
  
  -  the CICSPlex SM supplied starter set viewsets and menus,
     EYUEVK01 (English), EYUKVX01 (Japanese), EYUSVX01 (simplified
     Chinese), have been updated so that the MAS viewset now
     displays action buttons for STOPUNCON and FORCEDISCON.  If
     either button is selected, a confirmation panel will be
     displayed for the selected action, and YES must be responded
     to process the action.
  
  -  method EYU0CPLM (CPLM), which is called to return information
     about a MAS, has been updated to provide a MAS's ASCB address
     if so requested.  The method argument list (MAL) for CPLM,
     EYUZCPLM, has been updated to allow a caller to request a
     MAS's ASCB address.
  
  -  method EYU0TSUM (TSUM), which is called to issue MAS
     action's, has been updated to issue the STOPUNCON and
     FORCEDISCON actions.  The MAL for TSUM, EYUZTSUM, has been
     updated to allow the STOPUNCON and FORCEDISCON actions to be
     requested.
  
     When STOPUNCON is requested, the CSDB flag is turned on and
     then the request is sent to the MAS.
  
     When FORCEDISCON is requested, the CSDB STOPUNCON flag is
     queried, and if it is not turned on, the request is not
     honored, and a status STOPUNCON_REQUIRED is returned to the
     caller.  If the flag turned on, a call is made to CPLM to
     return the ASID and ASACB address of the MAS, and then the
     ESSS terminate command is issued.  If the ESSS terminate call
     completes successfully, new message EYUTS0026I will be issued
     by TSUM.  The text of this new message is as follows:
  
       EYUTS0026I  User <userid> has issued the FORCEDISCON action
                   for MAS <masname> - APPLID(<applid>)
                   CICSplex(<plexname>).
  
  -  Copybook EYUUTPEQ and module EYUTTSM0 have been updated to
     define new message EYUTS0026I.
  

Temporary fix

• FIX AVAILABLE BY PTF ONLY
  

Comments

APAR Information

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

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

  PK64919 UK39046

Modules/Macros

•    EYUA2443 EYUCTSUM EYUC2443 EYUEVX01 EYUE2443
  EYUKVX01 EYUK2443 EYUL2443 EYUN2443 EYUP2443 EYUQCPLM EYUQTSUM
  EYUQXESV EYURCPLM EYURTISD EYURTSUM EYURXECB EYURXEER EYURXEET
  EYUR2443 EYUSVX01 EYUS2443 EYUTAB2M EYUTRCOM EYUTRTOP EYUTTSM0
  EYUTXEMS EYUTXEPC EYUT2443 EYUUTPEQ EYUUXEEQ EYUYCPLM EYUYTSUM
  EYUY2443 EYUZCPLM EYUZTSUM EYU0CPLM EYU0TSUM EYU0TSVM EYU2XEEC
  EYU2XEET EYU2XERT EYU9CMPU EYU9CMP3 EYU9CMP4 EYU9CMP5 EYU9TSPU
  EYU9TSP3 EYU9TSP4 EYU9TSP5 EYU9XECS EYU9XEET EYU9X310 MAS
  

Fix information

• Fixed component name

  CPSM CICS 3.1

• Fixed component ID

  5655M1501

Applicable component levels

• R100 PSY UK39046

     UP08/08/20 P F808

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.