PM93397: CICS TG initialization fails when CTG_XA_MAX_TRAN is set to a low value.

Obtain the fix for this APAR.

APAR status

• Closed as program error.

Error description

• When CTG_XA_MAX_TRAN specifies a small value, CICS TG fails to
  start and issues messages:
  CTG6686E Unable to initialize JNI library: [EXCI_NOT_AVAILABLE]
  CTG6513E CICS Transaction Gateway failed to initialize
  CTG0827W CTGBATCH Child completed with a non-zero return code 1
  
  JNI trace shows:
  CTG9252T Exiting function 'xmt_addEntry' (return code '1006')
  CTG8642E Error storing XID (xmt_rc = 1006)
  
  There is not enough information to determine why the Gateway
  daemon fails to start.
  
  Additional search words:
  CTG6686 msgCTG6686E msgCTG6686 CTG6513 msgCTG6513E msgCTG6513
  CTG0827 msgCTG0827W msgCTG0827 CTG8642 msgCTG8642E msgCTG8642
  

Local fix

• Set CTG_XA_MAX_TRAN to 1000 or more.
  

Problem summary

• ****************************************************************
  * USERS AFFECTED: All users of CICS Transaction Gateway.       *
  ****************************************************************
  * PROBLEM DESCRIPTION: CICS TG does not provide enough         *
  *                      information to determine the cause of   *
  *                      errors occcuring because                *
  *                      CTG_XA_MAX_TRAN specifies a small       *
  *                      value.                                  *
  ****************************************************************
  * RECOMMENDATION:                                              *
  ****************************************************************
  When environment variable CTG_XA_MAX_TRAN was set lower than
  the number of heuristically-completed Units of Recovery (URs)
  retrieved from RRS during CICS TG start-up, CICS TG did not
  process all the returned URs and initialization failed.
  Additionally, for CICS TG V8.0 configured with CTG_EXCI_INIT=NO,
  if the number of heuristically-completed URs retrieved from
  RRS during CICS TG start-up exceeded the value set for
  CTG_XA_MAX_TRAN, then the Gateway daemon initialization
  complete successfully, but subsequent XA transactions failed
  with rc=-9 ECI_ERR_SYSTEM_ERROR.
  Non-XA transactions completed successfully.
  The documentation provided  was not sufficient to determine
  the cause of the failures.
  

Problem conclusion

• CICS TG has been changed. If CTG_XA_MAX_TRAN specifies a value
  lower than the number of incomplete  URs retrieved from RRS
  during CICS TG start-up, the Gateway daemon fails to
  initialize.
  
  The description of environment variable CTG_XA_MAX_TRAN in
  CICS TG for z/OS Information Center has been updated:
  
  CTG_XA_MAX_TRAN
  Set this environment variable to limit the maximum number of
  concurrent XA transactions that can use the EXCI or IPIC
  protocol in a Gateway daemon. The range of values is 1 to
  8192. The default value for a Gateway daemon is 1000. This
  variable requires a numeric entry.
  CICS Transaction Gateway allocates an amount of additional
  storage on startup approximately equivalent to 200 * the value
  of CTG_XA_MAX_TRAN bytes. For example, if the value of
  CTG_XA_MAX_TRAN is 1024, CICS Transaction Gateway allocates
  approximately 200 KB of additional storage on startup. This
  storage is also used during start up to process heuristically-
  completed units of recovery from the Gateway and any others in
  the same HA Group.
  For more information see "Highly available Gateway group" and
  "Cold Start".  It is good practice to set the value of
  CTG_XA_MAX_TRAN to be 1000 or a value greater than the number
  of configured connection managers, which ever is the larger.
  
  The following messages have been updated:
  CTG6686E Unable to initialize JNI library:  {error}
  Explanation:
  The ctgjni library could not be initialized.
  System Action:
  The CICS Transaction Gateway fails to start.
  User Action:
  The associated error gives more information about the cause.
  If the error indicates a problem locating the JNI library,
  ensure that it is available on the path shown by the error.
  If there was a security exception, ensure that the library has
  the correct access privileges.
  If the EXCI is unavailable, check the JNI log for further
  details. If the resource manager could not be started, check
  the JNI log for further details.
  After the error has been resolved start the CICS Transaction
  Gateway.
  
  CTG8642E Error storing XID (xmt_rc = {reason code})
  Explanation:
  The CICS Transaction Gateway has received a request to start a
  transaction, but could not store temporary information needed
  to identify the transaction.
  System Action:
  The CICS Transaction Gateway cannot start the transaction.
  User Action:
  If the problem persists, increase the value of the
  'CTG_XA_MAX_TRAN' environment variable for the Gateway.  The
  default value is 1000.
  
  The following message has been introduced:
  CTG9250E Error storing information about {number of URs}
  heuristically-completed units of recovery  (rc = {reason code})
  Explanation:
  During the start of a Gateway with XA enabled, the
  initialization of the resource manager processes
  heuristically-completed transactions.  These transactions may
  come from this Gateway or any Gateway in the same HA Group.
  For more information see the "Highly available Gateway group"
  and "Cold Start" sections of the CICS Transaction Gateway
  Information Center.  The maximum number of units of recovery
  that can be processed is controlled by the environment
  variable 'CTG_XA_MAX_TRAN'.  The default value is 1000.
  The first unit of recovery after this limit will cause
  initialization to stop.
  System Action:
  The CICS Transaction Gateway fails to start.
  User Action:
  As there are at least {number of URs} URs to process, the
  value needs to be increased.  Use the RRS administrative
  panels in ISPF to find the number of URs in in-forget state
  for this Gateway and any others with the same APPLID
  qualifier.
  

Temporary fix

Comments

APAR Information

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

  PM83321

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

  UK96061

Modules/Macros

•    CTG00201 CTG00204 CTG00470 CTG00471 CTG00524
  CTG00555 CTG00565 CTG00567 CTG00568 CTG00591 CTG00592
  

Fix information

• Fixed component name

  CTG V9 FOR Z/OS

• Fixed component ID

  5655Y2000

Applicable component levels

• R900 PSY UK96061

     UP13/08/09 P F308

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.