II12217: SET-UP CONSIDERATIONS FOR CICS TRANSACTION GATEWAY FOR OS/390

APAR status

• Closed as canceled.

Error description

• 5648B4300 R310
  This Information APAR is to document considerations for using
  the CICS Transaction Gateway for OS/390.
  - MAINTENANCE :
    10/2/2000 - Version 3.1.2 is now available, from the url :
    www-4.ibm.com/software/ts/cics/platforms/clients/ctg31pdt.htm
    This maintenance release contains fixes for the following
    APARs :
  
    PQ37626
    PQ39377
    PQ39725
  
    Version 3.1.1 of the CICS Transaction Gateway, released on
    5/15/2000 is no longer available for download.
  
    Maintenance in 3.1.1 contained fixes for the following
    APARs :
  
    PQ31837
    PQ33058
    PQ33193
    PQ34159
    PQ34553
    PQ35123
    PQ35228
    PQ35333
  
    The maintenance also includes a development (non-APAR) fix
    for unpredictable problems caused by PINGFREQUENCY processing.
    Symptoms of this problem include hangs, duplicate requests or
    incorrect commareas being returned.
  
    For further information, please refer to the readme.txt file
    found in the ctg root (/ctg) directory after the product has
    been downloaded, uncompressed and un-tar'ed.
  
  - MIGRATION from 310
    The 310 -time parameter is obsolete. Timestamping of messages
    is now the default, and may be turned off with the parameter
    -notime. If -time is used the CTG will terminate.
  
  - ECI_ERR_SECURITY_ERROR  -27
    Possible causes for this return code include:
    1.  Surrogate checking has been enabled in the EXCI via
        DFHXCOPT.  The parameter is SURROGCHK, which defaults to
        YES.  Refer to CICS External Interfaces Guide under
        External CICS Interface for details of using this
        parameter.
    2.  RACF program control must be active for the SDFHEXCI
        dataset.  To activate program control:
        SETROPTS CLASSACT(PROGRAM)
        RDEFINE PROGRAM * UACC(READ)
        SETROPTS WHEN(PROGRAM)
        To add the CICS library when program control is active:
        RALTER PROGRAM * ADDMEM*'hlq.SDFHEXCI'/volser/NOPADCHK)
        SETROPTS WHEN(PROGRAM) REFRESH
    3.  Extended attributes settings are necessary for certain HFS
        files.  The following extattr commands mark the load
        modules used by the CTG as program controlled:
        extattr +p /ctg/bin/lib*.so
        extattr +p /ctg/bin/SECURES
        Force JVM to use its own non-sharable address space:
        extattr -s <path>/ctg/bin/ctgstart
        Certain MVS Java files must also be program controlled:
        extattr +p <javapath>/bin/*
        extattr +p <javapath>/bin/mvs/native_threads/*
        extattr +p <javapath>/lib/mvs/native_threads/*
        For further information, see CICS Transaction Gateway for
        OS/390 Administration
    4.  The ctgstart script must have the 'Share Address Space'
        extended attribute bit turned off with extattr -s. If
        not, on OS/390 2.8 or above a -27 will result on ECI_SYNC
        or ECI_STATE-SYNC calls due to a 'dirty' address space.
        This problem does not occur at OS/390 2.6.
    5.  If using userids and passwords that are to be verified by
        the gateway itself, and not passed to CICS for
        verification, then a RACF facilityclass must be defined.
        The name of the facility class must match the netname
        parameter on the CONNECTION definition for the EXCI link,
        and the value of the DFHJVPIPE environment variable used
        by the gateway.
    6.  If using OEM ACF2 Security package, SDFHEXCI must be in
        an APF authorized library, or it must be in ACF2's
        linklist GSO LINKLST.
  
        ACF2 6.2 had a zap (TA4328D) to turn on the "dirty" bit
        (TCBNCTL), but this support was present in the base of
        6.3.  The -27 can surface when changing ACF2 releases,
        depending on if TA4328D was applied to the 6.2 system.
  
        SDFHEXCI must be "program controlled" and in the ACF2
        realm this has the additional requirement that either:
  
        a) SDFHEXCI dataset must be APF authorized
        or
        b) SDFHEXCI dataset must be in GSO LINKLST (ACF2's
           LINKLIST)
  
        NOTE:  IEASYSxx PARMLIB member specifies LNKAUTH=APFTAB
  -9 ECI_ERR_SYSTEM_ERROR
     1. This return code can be generated as a result of problems
        in the CICS address space. For example, PGMIDERR, a
        security violation, or program-autoinstall veto.
     2. It can also be generated in the EXCI code if the userid
        of the CTG host address space is not PERMITted to the
        DFHAPPL.<dfhjvpipe> or the DFHAPPL.<applid> Facilities.
  
  - "Dirty Address Space" problems :
    1.  This problem appears in different ways depending on the
        point at which the CTG loses its privileged status.
    2.  The ctgstart script still has the 's' bit set.
    3.  The SDFHEXCI load library, and any load library defined in
        the EXCI_OPTIONS variable are not program-controlled.
    4.  The CTG HFS is mounted with NOSETUID. The CTG HFS must be
        mounted with the default of SETUID.
  
  - msgEDC5111I PERMISSION DENIED :
    1.  A CTG port is already in use by another task.
    2.  A port is reserved for the CTG job in the TCPIP.PROFILE,
        but the CTG jobname is less than 8 characters. In this
        case the job which attempts to open the port will have a
        jobname with a numeric suffix allocated by OMVS and will
        not match the TCPIP.PROFILE jobname. Either 1) Do not
        reserve the port, or 2) Use an eight character jobname,
        or 3) Add 'OMVS' to the list of ids allocated the port
        in the TCPIP.PROFILE. It is not advisable to anticipate
        the numeric character added by OMVS as an id.
  
  - JAVA_HOME variable :
    1.  Ensure the variable is available in the environment of the
        process which runs the ctgstart script.
  
  - java.lang.OutOfMemoryError, or NullPointerException
    1. Programs which use network JavaGateway() connections must
       ensure that JavaGateway objects are closed when no longer
       required. If not, the connections will remain open for the
       lifetime of the CTG JVM, resulting in out of memory errors
       or failed connections when the CTG.INI maxconnect value is
       reached.
    2. These symptoms may also be caused by: 1) the BPXPRMxx value
       for MAXTHREADS being reached. The solution is to increase
       MAXTHREADS. 2) Use of REGION=0M in the CTG JCL. The actual
       region size available when 0M is used is unpredictable and
       may be less than required for the number of threads being
       run by the CTG. The solution is to allocate an explicit
       region. The value is dependent on the number of threads
       required to be run by the CTG. 3) The JVM default stack
       size values -ss (256k) and -oss (400k) result in a memory
       allocation of 656k per thread. Halving these values on the
       'exec java' in ctgstart will reduce memory consumption.
  
  - Servlets
    1. Servlets which employ JavaGateway objects must ensure
       references to the gateway objects are threadsafe.
  
  - Tracing in servlets and other CTG client applications.
    There are two ways to activate tracing of client code :
    1.  Add method invocations on the 'T' object in the client
        application source. For example :
        T.setOn(true)       activates standard tracing.
        T.setDebugOn(true)  activates extended tracing.
        T.setTimingOn(true) timestamps the trace entries.
        Using (false) will deactivate the trace/timing.
        The following method calls are also available :
        T.setEntryOn(true/false)
        T.setExitOn(true/false)
        T.setLinesOn(true/false)
        T.setStackOn(true/false)
  
    2.  Set the following properties :
        Gateway.T.trace=on
        Gateway.T=on
        Gateway.T.entry=on
        Gateway.T.exit=on
        Gateway.T.lines=on
        Gateway.T.stack=on
        Gateway.T.timing=on
  
     If the local protocol is used by the client code then
     activating the client trace will also activate the server
     trace.
     If network protocols are used, the server trace can be
     activated, at CTG daemon startup only, with the -trace and
     -X switches on the ctgstart script invocation.
  
  - JNI trace.
  
    As an alternative to running a full GTF trace to capture the
    CTG's EXCI activity (see CICS/TS External Interface Guide for
    details of GTF trace of EXCI), a JNI trace can be obtained.
    To do so, add the following statement to the ctgstart script :
    'export CTG_JNI_TRACE=<hfs filename>' where <hfs filename> is
    the name of a file in the HFS to which the trace output will
    be written.
  
    To obtain a JNI trace for a local mode connection from a
    servlet under WAS, do the following :
    1) Set CTG_JNI_TRACE=<filename> in the httpd.envvars
    2) Modify the IHS JCL to specify parameters to LE as follows :
       LEPARM='ENVAR("_CEE_ENVFILE=/your/httpd.envvars")'
    3) Ensure the userid under which WAS is running has write
       permission to the trace output file/directory.
  

Local fix

Problem summary

Problem conclusion

Temporary fix

Comments

• CLOSING CAN PER INFO APAR GUIDELINES
  

APAR Information

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

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

Fix information

Applicable component levels