IBM CICS Transaction Gateway Version 7.0.1.1 - README for Linux on zSeries

IBM CICS Transaction Gateway Version 7.0.1.1 - README for Linux on zSeries

The product documentation is provided as an Eclipse Information Center available at: http://publib.boulder.ibm.com/infocenter/cicstg/v7r0m0/index.jsp

This file contains important information about the IBM CICS Transaction Gateway (CICS TG) that might not be available in the Eclipse Information Center.

This readme file is available in plain text and HTML. Both files contain the same information. After installation the files are included in the <install_path> directory.

The text version of this file is suitable for use with a screen reader or braille device.

SUMMARY OF TOPICS

INSTALLING AND UNINSTALLING A FIX PACK

This section applies to running the Fix Pack utility which updates an existing installation of the product.

The Fix Pack utility runs in console mode and must be run by a user with root privileges.

Before installing or uninstalling the Fix Pack shut down any local CICS TG applications, the Gateway daemon and then the Client daemon.

It is strongly recommended that you shut down all programs running on your system before running the Fix Pack utility.

INSTALLING THE FIX PACK

Change to the directory where the Fix Pack has been unpacked and issue the following command:

ctgfix

The installer will prompt for confirmation before installing. Enter 'y' to proceed. If you do not wish to be prompted for confirmation, issue the command:

ctgfix -y

During installation, the Fix Pack utility creates a log file named <CICS TG install path>/ctgfix/ctgfix.log. The log file contains details of each file that is updated by the Fix Pack, and details of any errors. Further information about the error messages is available in text file ctgfix.hlp located where the Fix Pack has been unpacked.

If the CICS TG is using messages that are not in English, issue the ctgmsgs command to switch to your language of choice:

ctgmsgs XX code_set

For help on the ctgmsgs command, issue the command:

ctgmsgs -?

UNINSTALLING A FIX PACK

Change to the <CICS TG install path>/ctgfix directory and issue the following command:

ctgfix -u

The Fix Pack utility will prompt for confirmation before uninstalling. Enter 'y' to proceed. If you do not wish to be prompted for confirmation, issue the command:

ctgfix -u -y

During uninstall, the Fix Pack utility appends to the ctgfix.log file. The log file contains details of each file that is restored by the Fix Pack, and details of any errors. Further information about the error messages is available in text file <CICS TG install path>/ctgfix/ctgfix.hlp.

INSTALLING THE PRODUCT

Installation and uninstallation must be done by the root user.

Before you install, check the root user's umask to ensure that files created during the installation are readable by the user IDs that will run the CICS TG. A umask of 077 restricts access to the root user that installed the CICS TG; a umask of 022 allows all users to run the CICS TG.

USING THE INSTALLSHIELD WIZARD

This section is an aid for installation, the following details list the commonly used options. More information on how to use the installer can be found in the section "Known issues during installation or uninstallation" and the Eclipse Information Center.

To install the CICS TG launch the InstallShield wizard:

installer

To install the CICS TG in console mode launch the InstallShield wizard with the -console option:

installer -console

To install the CICS TG with no user interaction launch the InstallShield wizard with the -silent and -V licenseAccepted options:

installer -silent -V licenseAccepted=true

INSTALLING THE JAVA RUNTIME ENVIRONMENT

The supplied version of Java is IBM 31-bit Runtime Environment for Linux on zSeries architecture, Java 2 Technology Edition, Version 5 Service Release 4.

To install the RPM package file, run the command:

rpm -i -v ibm-java2-s390-jre-5.0-4.0.s390.rpm

After installing the Java Runtime Environment read the Java documentation for guidance on how to define the PATH and other environment variables.

CICS TG STATISTICS API DOCUMENTATION

Reference documentation for the statistics API is included in the information center. The documentation is also included as part of the CICS TG installation, in <install_path>/docs/ctgstatsdoc.zip. To view the documentation, expand the contents of the ZIP file into a suitable directory and view file 'index.html' with a Web browser.

NEW JAVA CLIENT CIPHER SUITE SELECT FEATURE

Cipher suites define the key exchange, data encryption, and hash algorithms used for a SSL session between a client and server. During the SSL handshake both sides present the cipher suites they are able to support and the strongest one common to both sides is selected. This new feature allows you to restrict the cipher suites that a Java Client application presents.

RESTRICTING CIPHER SUITES FOR JAVA CLIENT APPLICATIONS

To restrict the cipher suites used by a JavaGateway object, use the setProtocolProperties() method to add the property (JavaGateway.SSL_PROP_CIPHER_SUITES) to the properties object passed to the it. The property's value must contain a comma-separated list of the cipher suites that the application is restricted to using. For example:

Properties sslProps = new Properties();
sslProps.setProperty(JavaGateway.SSL_PROP_KEYRING_CLASS, strSSLKeyring);
sslProps.setProperty(JavaGateway.SSL_PROP_KEYRING_PW, strSSLPassword);
sslProps.setProperty(JavaGateway.SSL_PROP_CIPHER_SUITES,
                     "SSL_RSA_WITH_NULL_SHA");
javaGatewayObject = new JavaGateway(strUrl, iPort, sslProps);

RESTRICTING CIPHER SUITES FOR RESOURCE ADAPTERS

In the WebSphere Administration console, change the "CipherSuites" custom property for the connection factory to a comma-separated list of the cipher suites that this connection factory is restricted to use.

ACCESSIBILITY FEATURES

STARTING THE GATEWAY DAEMON FROM A COMMAND PROMPT USING A SCREEN READER

In some Telnet sessions, the screen reader might re-read CICS TG log output or the command prompt, after the CICS TG has started. This is expected behavior, and does not mean that the CICS TG has failed to start. To determine if the CICS TG started correctly, listen for the message:

'CTG6512I CICS Transaction Gateway initialization complete'.

If the CICS TG did not start successfully, this message is output:

'CTG6513E CICS Transaction Gateway failed to initialize'.

USING SNA ON SLES 9 64-BIT

The SNA protocol requires the use of the LD_PRELOAD environment variable to set the location of the Linux streams (LiS) libraries. The LD_PRELOAD environment variable does not work correctly on SLES 9 64-bit due to a defect in the operating system. This can be resolved by ugrading to SLES 10, or installing a 31-bit shell for use with the CICS TG.

USING IBM COMMUNICATIONS SERVER FOR LINUX REMOTE API CLIENT 6.3

IBM Communication Server for Linux Remote API Client 6.3 and above no longer requires the LD_PRELOAD of the Linux streams (LiS) library. Set LD_PRELOAD to an empty string, for example:

export LD_PRELOAD=""

SECURITY-ENHANCED LINUX (SELINUX)

CICS TG does not support Security-Enhanced Linux.

INSTALLING ON RED HAT ENTERPRISE LINUX (RHEL) 5

To install and run on RHEL 5 the CICS TG product depends on shared libraries that are not installed by default. The RPM's that contain these libraries are:

libXp-1.0.0-8
compat-libstdc++-296-2.95.3

To use CICS TG on RHEL 5 export the LD_LIBRARY_PATH environment variable to include /opt/ibm/cicstg/lib/stdc++6

KNOWN ISSUES DURING INSTALLATION OR UNINSTALLATION

THE GRAPHICAL USER INTERFACE STOPS RESPONDING

When installing with the graphical user interface the installer program may stop responding. If this problem occurs, issue "Ctrl C" to end the installer program and retry the installation using the "-console" option.

INCORRECT PROGRESS DISPLAYED WHEN MIGRATING FROM OLDER VERSIONS

When upgrading from earlier versions of the CICS TG the installer program does not display progress correctly; ignore the progress display. The installation is unaffected by the incorrect progress display.

RECORDING A RESPONSE FILE

If you create a response file using the installer "-options-record" option with the "Custom" installation selected, you must modify the file before you use it. Find the line:

-W setupTypes.selectedSetupTypeId=custom

and replace it with:

-W setupTypes.active=false

If you do not modify the response file before use, all features will be installed.

USING A RESPONSE FILE

When installing silently the license must be accepted, this is done with the -V option. The following command is for silent installation with a recorded response file.

installer.exe -options "response_file_name" -silent -V licenseAccepted=true

'NO SUCH FILE' ERROR MESSAGE OUTPUT DURING UNINSTALLATION

Messages similar to the following might be output during uninstallation:

cat: /tmp/istemp2752209095151/chunk2: No such file or directory
rm: cannot remove `/tmp/istemp2752209095151/chunk1': No such file or directory
rm: cannot remove `/tmp/istemp2752209095151/chunk2': No such file or directory

The uninstallation completes successfully, and you can ignore these messages.

UNINSTALLATION FAILS WITH 'ENGINE IS MISSING' MESSAGE

If the uninstallation is not performed by a user ID with root privileges, the uninstallation fails, and the following error might be output to the console.

"engine is missing (/root/InstallShield/Universal/common/Gen1):"

The CICS TG must be uninstalled by a user with root privileges.

SERVICE AND UPDATES

Below is a list of APARs included in this version of the CICS Transaction Gateway. All APARs listed are applicable to this platform. Full details can be found on the support pages: http://www-306.ibm.com/software/htp/cics/ctg/support/

APARS INCLUDED IN 7.0.1.1

PK51695
MAXCONNECT not logged when hit

PK52648
CICS TG does not use unique network UOW identifiers using the SNA protocol driver

PK52798
In local mode, CICS ECI resource adapter unable to handle some special characters in password causing security failure.

PK54463
The exclamation mark in a valid password returns ECI_ERR_SECURITY_ERROR (rc=-27)

PK54693
Client daemon tracepoint CCL5896 contains invalid values for the error code.

PK55050
Client daemon may not correctly report status of a TCP62 link

PK55173
Invalid userid or password on ECI request results in RC-9 ECI_ERR_SYSTEM_ERROR returned by CICS TG

PK56203
After a keepalive timeout on a TCP62 connection, the client daemon is unable to reconnect to the CICS server.

PK57381
Backslash in trace filename prevents memory mapped wrapping trace starting

PK59463
Update to version of ccf2.jar shipped with CICS TG

PK60170
ECI timeout causes a DFHIE1001 bracket protocol violation message

PK62107
CICS TG receives SIGSEGV when attemping to connect to CICS using TCP/IP

PK62540
TCP/IP Keepalive flows are not active on TCP62 connections resulting in unexpected connection terminations.

PK66998
GetConnection() is returning a null when it should return an exception

PK67935
Client dameon not reconnecting correctly after third occurrence of send call failure

PK68109
Network sockets not closed

PK68968
Fixes to the TCP/IP protocol driver

PK68969
Log message CCL2010 displays incorrectly formatted return code

PK69017
ECIConnection.close() JavaDoc incorrectly states when a ResourceException will be thrown

PK69132
If a Mode Name is rejected by CICS, the CICS TG Client daemon receives a TCP/IP error when releasing the connection.

PK69840
Client daemon appears to become unresponsive during startup

PK70913
CICS Client trace function not able to track when CICS_EPITERMINATE call exits

APARS INCLUDED IN 7.0.1

PK33952
Client daemon may hang when tracing is enabled.

PK33954
The CICS TG hangs when Client daemon tracing is enabled

PK32530
CICS TG may fail to connect to CICS on iSeries

PK30770
Expired passwords cannot be changed using PEM under CICS TG with the TCP62 protocol

PK36915
After a send() call fails, reconnect attempts are not occurring

PK40853
Duplicate PCID's being sent to VTAM

PK42521
Incoming ATI causes Client daemon abend

PK42522
Multiple ATI transactions through EPI applications fail

PK42524
Client daemon ends when unable to establish a connection to CICS

PK42562
CICS TG uses high CPU during network problems

PK42564
CICS TG trace outputs data lengths incorrectly

PK45302
CICS TG Client daemon hangs intermittently on multi-processor machines

PK47041
CICS TG receives an out of memory error from pthread_create()

PK47051
CICS TG J2EE samples give warnings when compiling

APARS INCLUDED IN 7.0

PK11029
CTG8404I message is not documented in the CICS TG messages book

PK20438
CICS TG Administration manual is unclear with respect to use of IKEYMAN and validity of X509 V3 certificates

PK26886
Connection logging messages appearing in stderr

PK16738
Client driver triggers bracket protocol error on CICS host.

PK23200
CICS TG and CICS UC fail to reconnect to CICS after a network outage.

PK27139
Socket send() hangs due to hardware problem. Added timeout to call in the cclclnt.

PK27140
Client daemon log message CCL2010 does not always contain full diagnostic information and appears corrupt

Contact your IBM Support organization for service and updates to the product.

THIRD PARTY LICENSE TERMS AND CONDITIONS, NOTICES AND INFORMATION

The Program includes "UnZipSFX stub" software from the Info-Zip group which is Copyright (c) 1999-2002, Info-ZIP. All rights reserved. IBM did not modify the UnZipSFX software. There are no extra charges or costs due to the use of this code, and the original compression sources are freely available from http://www.info-zip.org/pub/infozip/ or ftp://ftp.info-zip.org/pub/infozip/ on the Internet.

LINUX COPYRIGHT STATEMENTS AND LICENSING NOTES

This product uses the following libraries from the glibc package:

ld.so, libc.so, libm.so, libdl.so, libnsl.so, librt.so and libpthread.so.

Refer to the glibc package on your machine for the various copyright statements and licensing terms for these libraries.

This product also uses libncurses.so from the ncurses package. Again, refer to this package on your machine for the copyright statement and licensing terms applicable to this library.

IMPORTANT NOTE:

Your use of the libgcc or libstdc++ packages will be subject to the GNU GPL licence terms which could require you to provide source code in certain circumstances. In this connection, please bear in mind that IBM will not supply source code, e.g. for the CICS TG C++ libraries.


© Copyright IBM Corporation 2009. All rights reserved.
For legal information, see http://www.ibm.com/legal/copytrade.shtml