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

A fix is available

Subscribe

You can track all active APARs for this component.

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 number

    PM83321

  • Reported component name

    CTG V8 FOR Z/OS

  • Reported component ID

    5655W1000

  • Reported release

    810

  • Status

    CLOSED PER

  • PE

    NoPE

  • HIPER

    NoHIPER

  • Special Attention

    NoSpecatt

  • Submitted date

    2013-02-21

  • Closed date

    2013-07-22

  • Last modified date

    2013-09-03

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

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

    PM93397 UK96059 UK96060

Modules/Macros

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

Publications Referenced
SC34713200 SC34723100      

Fix information

  • Fixed component name

    CTG V8 FOR Z/OS

  • Fixed component ID

    5655W1000

Applicable component levels

  • R800 PSY UK96059

       UP13/08/09 P F308

  • R810 PSY UK96060

       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.



Rate this page:

(0 users)Average rating

Document information


More support for:

CICS Transaction Gateway
CTG

Software version:

8.1.0.0

Reference #:

PM83321

Modified date:

2013-09-03

Translate my page

Machine Translation

Content navigation