CICS Transaction Gateway: UNIX and Linux Administration - IBM

CICS Transaction Gateway
UNIX and Linux Administration
Version 7.0
���
SC34-6752-00

CICS Transaction Gateway
UNIX and Linux Administration
Version 7.0
���
SC34-6752-00

Note!
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
243.
First Edition (November 2006)
This edition applies to Version 7.0 of the CICS Transaction Gateway, program number 5724-I81. It will also apply to
all subsequent versions, releases, and modifications until otherwise indicated in new editions.
This edition replaces SC34-6372. Technical changes to the text are indicated by a vertical line to the left of the
change.
© Copyright International Business Machines Corporation 1996, 2006. All rights reserved.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
About this book . . . . . . . . . . . vii
Installation path . . . . . . . . . . . . viii
What’s new on the CICS Transaction
Gateway on the UNIX and Linux
platform . . . . . . . . . . . . . . ix
Chapter 1. CICS Transaction Gateway
overview . . . . . . . . . . . . . . 1
CICS Transaction Gateway Version 7.0 scenarios . .2
What CICS Transaction Gateway provides . . . .3
A Gateway daemon . . . . . . . . . . .3
The Gateway classes . . . . . . . . . . .3
J2EE resource adapters . . . . . . . . . .4
A Client daemon . . . . . . . . . . . .4
The external access interfaces (ECI, EPI, ESI) . . .4
Additional functions . . . . . . . . . . . .5
3270 terminal emulation (cicsterm) . . . . . .5
3270 printer support (cicsprnt) . . . . . . .5
Controlling the CICS Transaction Gateway . . .5
Controlling the CICS Transaction Gateway
dynamically . . . . . . . . . . . . .6
Network security . . . . . . . . . . . . .6
Encryption . . . . . . . . . . . . . .7
Digital signatures and digital certificates . . . .7
Obtaining a digital certificate . . . . . . . .8
Key rings and KeyStores . . . . . . . . .9
Authentication using SSL . . . . . . . . .9
Security exits . . . . . . . . . . . . .10
The J2EE resource adapters . . . . . . . . .10
Dynamic Logical Partitioning (DLPAR, AIX only) . .11
Local mode explained . . . . . . . . . . .11
Benefits of local mode . . . . . . . . . .12
Benefits of remote mode . . . . . . . . .16
Considerations when deciding whether to use
local mode . . . . . . . . . . . . .17
Enabling local mode . . . . . . . . . .17
Chapter 2. Planning your installation 19
Hardware requirements . . . . . . . . . .19
Supported software . . . . . . . . . . . .19
Operating systems . . . . . . . . . . .19
Web browsers . . . . . . . . . . . .21
Java support for the Gateway daemon . . . .21
Java support for the resource adapters and Java
Client applications . . . . . . . . . . .21
JSSE . . . . . . . . . . . . . . .22
CICS servers . . . . . . . . . . . . .22
J2EE application servers . . . . . . . . .22
SNA communications . . . . . . . . . .23
TCP/IP communications . . . . . . . . .23
TCP62 communications . . . . . . . . .23
Compilers and application development tools .23
Other tools . . . . . . . . . . . . .24
GPL licence and copyright issues on Linux . . .24
CICS server PTF requirements . . . . . . . .24
Terminal Sign-on capability . . . . . . . .24
Timeout support . . . . . . . . . . . .24
Communication with CICS servers . . . . . .25
Restrictions on CICS Transaction Server for
iSeries . . . . . . . . . . . . . . .26
Why use a particular protocol? . . . . . . .26
DBCS multibyte characters . . . . . . . . .26
Server code page support . . . . . . . . . .27
Chapter 3. Installing the CICS
Transaction Gateway . . . . . . . . 29
Choosing what to install . . . . . . . . . .29
Before you install the CICS Transaction Gateway . .29
Known issues . . . . . . . . . . . . .29
Installing with the InstallShield wizard . . . . .30
Installing from the console . . . . . . . . .30
Installing silently . . . . . . . . . . . .31
Creating a response file . . . . . . . . .31
Using the response file to install silently . . . .31
Installing silently with no response file . . . .31
Actions after installation . . . . . . . . . .31
Install the Java runtime environment . . . . .31
Installing a shared library on Red Hat Enterprise
Linux V3 . . . . . . . . . . . . . .31
Adding features after installation . . . . . . .32
Removing features . . . . . . . . . . . .32
Updating the CICS Transaction Gateway . . . .32
Uninstalling the CICS Transaction Gateway . . . .32
Uninstalling from the console . . . . . . .32
Uninstalling silently . . . . . . . . . .32
Installation and uninstallation logs . . . . . .32
National language support . . . . . . . . .33
Using an alternative code set on AIX . . . . .33
Using an alternative code set on other operating
systems . . . . . . . . . . . . . . .34
Using X-Window System from a remote system . .34
Chapter 4. Setting up communication
with CICS servers . . . . . . . . . . 37
TCP/IP configuration . . . . . . . . . . .37
Verifying the TCP/IP installation . . . . . .37
On CICS Transaction Server for z/OS . . . .37
Next steps . . . . . . . . . . . . . .39
TCP62 configuration . . . . . . . . . . .39
On z/OS . . . . . . . . . . . . . .40
On CICS Transaction Server for z/OS . . . .40
On the client workstation . . . . . . . . .41
Firewall implications . . . . . . . . . .41
KeepAlive packets . . . . . . . . . . .41
Next steps . . . . . . . . . . . . . .41
SNA configuration . . . . . . . . . . . .41
Configuring for the CICS Transaction Gateway 42
Configuring SNA Communications product . .43
© Copyright IBM Corp. 1996, 2006 iii

|
Defining SNA connections on CICS Transaction
Server for z/OS . . . . . . . . . . . .44
Data conversion . . . . . . . . . . . . .45
Configuring message queues . . . . . . . .46
Message queues on HP-UX . . . . . . . .46
Message queues on Linux . . . . . . . .46
Message queues on Solaris . . . . . . . .47
Chapter 5. Configuration . . . . . . . 49
Before you start to configure your system . . . .49
Gather information . . . . . . . . . . .49
Configure your programming environment . . .49
Recommended Java options for the Solaris JVM 49
Using the Configuration Tool . . . . . . . .50
Running the Configuration Tool for a different
operating system . . . . . . . . . . .50
The Configuration Tool interface . . . . . .50
Configuring Gateway daemon settings . . . .53
Configuring Client daemon settings . . . . .64
Configuring Server settings . . . . . . . .70
Trace settings . . . . . . . . . . . . .79
Applying your changes to the system . . . .82
J2EE setup and configuration . . . . . . . .82
Transaction management models . . . . . .82
Deploying CICS resource adapters . . . . . .82
Tracing . . . . . . . . . . . . . . .87
The CICS Transaction Gateway logging facility . .88
Setting up the environment for CICS Transaction
Gateway logging . . . . . . . . . . .88
Sample configuration and mapping files . . . . .89
Keyboard mapping for cicsterm . . . . . . .89
Keyboard mapping file syntax . . . . . . .90
The keyboard mapping file . . . . . . . .90
Customizing the screen colors for cicsterm . . . .91
Color mapping syntax . . . . . . . . . .92
The color mapping file . . . . . . . . .92
Preparing to use local CICS Transaction Gateway
support . . . . . . . . . . . . . . . .93
Checking your configuration . . . . . . . .93
Chapter 6. Network Security . . . . . 95
Java Secure Socket Extension (JSSE) . . . . . .95
Migrating to JSSE . . . . . . . . . . .95
Migrating keys and certificates . . . . . . .95
Maintaining your digital certificates for JSSE . .96
Using iKeyMan to manage self-signed certificates
under JSSE . . . . . . . . . . . . .97
Using externally signed certificates under JSSE 100
Using keytool for certificate management . . . 100
Transport Layer Security . . . . . . . . . 105
Configuring CICS Transaction Gateway for SSL 106
SSL configuration settings . . . . . . . . 106
Using the SSL protocol . . . . . . . . . 106
Chapter 7. Client security . . . . . . 107
Client security overview . . . . . . . . . . 107
Default connection settings . . . . . . . . . 107
ECI security . . . . . . . . . . . . . . 108
EPI terminal security . . . . . . . . . . . 108
Changing the user ID and password . . . . 108
iv CICS Transaction Gateway: UNIX and Linux Administration
Password expiry management . . . . . . . . 109
Sign-on capable and sign-on incapable terminals 109
Specifying the sign-on capability of a terminal 109
Chapter 8. Performance . . . . . . . 113
Assessing system performance . . . . . . . .113
The CICS Transaction Gateway threading model 113
Tuning your configuration parameters . . . . .115
Java considerations . . . . . . . . . . .116
Other system factors . . . . . . . . . . .117
Tracing and performance . . . . . . . . .118
Performance monitoring tools . . . . . . . .118
Chapter 9. Operating the CICS
Transaction Gateway . . . . . . . . 121
Starting the CICS Transaction Gateway . . . . . 121
Stopping the CICS Transaction Gateway . . . . 121
Changing the system time . . . . . . . . . 121
Chapter 10. Operating the Gateway
daemon . . . . . . . . . . . . . . 123
Starting the Gateway daemon . . . . . . . . 123
Starting the Gateway daemon with preset
options . . . . . . . . . . . . . . 123
Starting the Gateway daemon with
user-specified options . . . . . . . . . 123
Stopping the Gateway daemon . . . . . . . 125
Running the Gateway daemon in the background 126
Administering your system . . . . . . . . . 126
Setting the Gateway trace . . . . . . . . 127
Setting the JNI trace . . . . . . . . . . 127
Setting Gateway and JNI trace . . . . . . . 127
Querying trace settings . . . . . . . . . 127
Shutting down the Gateway daemon . . . . 127
Getting help . . . . . . . . . . . . . 127
Administration options . . . . . . . . . 127
Chapter 11. Operating the Client
daemon . . . . . . . . . . . . . . 133
The cicscli command . . . . . . . . . . . 133
Starting the Client daemon . . . . . . . . 133
Starting connections with additional servers . . 134
Shutting down the Client daemon normally . . 134
Shutting down the Client daemon immediately 134
Restarting the Client daemon normally . . . . 134
Restarting the Client daemon immediately . . 135
Starting client tracing . . . . . . . . . . 135
Specifying the trace components . . . . . . 135
Stopping client tracing . . . . . . . . . 135
Security considerations for trace and log files 136
Setting up security for the Client daemon . . . 136
Displaying information about the version of the
Client daemon . . . . . . . . . . . . 137
Listing the connected servers . . . . . . . 137
Disabling the display of messages from the
Client daemon . . . . . . . . . . . . 137
Destination for error messages . . . . . . . 137
Displaying command options for the Client
daemon . . . . . . . . . . . . . . 137

|
|
|
|
|
|
|
cicscli command reference . . . . . . . . . 137
Changing the system time . . . . . . . . . 141
Chapter 12. Terminal Emulation . . . 143
Summary of Terminal Emulation commands . . . 143
The cicsterm command . . . . . . . . . . 143
Using cicsterm . . . . . . . . . . . . 143
Stopping a terminal emulator . . . . . . . 144
cicsterm and user exits . . . . . . . . . 144
cicsterm and RETURN TRANSID IMMEDIATE 144
Using clients for X-Window System . . . . . 145
Keyboard mapping in cicsterm . . . . . . 145
cicsterm command reference . . . . . . . . 145
The cicsprnt command . . . . . . . . . . 147
Using cicsprnt . . . . . . . . . . . . 148
cicsprnt and user exits . . . . . . . . . 148
cicsprnt and RETURN TRANSID IMMEDIATE 149
cicsprnt command reference . . . . . . . . 149
Chapter 13. Problem determination
and problem solving . . . . . . . . 153
Problem determination: preliminary checks . . . 153
What to do next . . . . . . . . . . . 154
Problems installing the product . . . . . . . 154
Problems with the Gateway daemon . . . . . 155
Messages . . . . . . . . . . . . . . 155
Tracing . . . . . . . . . . . . . . 155
Diagnosing common problems: Gateway
daemon . . . . . . . . . . . . . . 157
Problems with the Client daemon . . . . . . 162
Messages . . . . . . . . . . . . . . 162
Tracing . . . . . . . . . . . . . . 162
Diagnosing common problems: Client daemon 168
Problems with Client applications . . . . . 176
Telnet clients . . . . . . . . . . . . 176
Problems running the Configuration Tool . . . . 177
Program support . . . . . . . . . . . . 177
Reporting problems . . . . . . . . . . 177
Documenting problems . . . . . . . . . 178
Locating and compiling information . . . . . 179
Submitting the documentation . . . . . . . 179
APARs and fixes . . . . . . . . . . . 180
Chapter 14. Migration . . . . . . . . 181
Migrating to Version 7 . . . . . . . . . . 181
Migration considerations at Version 6 . . . . . 181
HTTP and HTTPS protocols . . . . . . . 181
Supported ECI and EPI versions . . . . . . 182
Configuration file: change of default name . . 182
User exits: change of file name . . . . . . 182
Linux C++ applications . . . . . . . . . 182
Deprecated features . . . . . . . . . . 182
Migration: support for resource adapters . . . . 183
Migrating from CICS Transaction Gateway Version
4 and earlier . . . . . . . . . . . . . . 183
Chapter 15. Statistics introduction 185
Which statistics do I need? . . . . . . . . . 185
Statistics for tuning and capacity planning . . 185
Statistics to diagnose system problems . . . . 186
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Statistics on resource usage . . . . . . . . 186
Statistics for throughput analysis . . . . . . 187
Setting up your system for statistics . . . . . . 187
Displaying statistics . . . . . . . . . . . 187
Displaying all available statistics . . . . . . 188
Selecting the statistics to display . . . . . . 188
Listing available resource groups . . . . . . 188
Listing all available statistical IDs . . . . . 188
Listing statistical IDs for selected resource
groups . . . . . . . . . . . . . . 189
Getting help on statistics . . . . . . . . 189
Resource groups . . . . . . . . . . . . 189
List of statistics . . . . . . . . . . . . . 189
Connection manager statistics . . . . . . . 190
Gateway daemon statistics . . . . . . . . 191
Protocol handler statistics . . . . . . . . 192
Worker thread statistics . . . . . . . . . 192
Appendix A. Data conversion when
using the Client daemon and a CICS
server . . . . . . . . . . . . . . 193
Supported conversions . . . . . . . . . . 193
Arabic . . . . . . . . . . . . . . . 194
Baltic Rim . . . . . . . . . . . . . 195
Cyrillic . . . . . . . . . . . . . . 195
Estonian . . . . . . . . . . . . . . 196
Greek . . . . . . . . . . . . . . . 196
Hebrew . . . . . . . . . . . . . . 196
Japanese . . . . . . . . . . . . . . 197
Korean . . . . . . . . . . . . . . 198
Latin-1 and Latin-9 . . . . . . . . . . 199
Latin-2 . . . . . . . . . . . . . . 200
Latin-5 . . . . . . . . . . . . . . 200
Simplified Chinese . . . . . . . . . . 201
Traditional Chinese . . . . . . . . . . 201
Vietnamese . . . . . . . . . . . . . 202
Unicode data . . . . . . . . . . . . 202
Appendix B. Editing the configuration
file ctg.ini . . . . . . . . . . . . . 203
ctg.ini: GATEWAY section . . . . . . . . . 203
TCP protocol . . . . . . . . . . . . 205
SSL protocol . . . . . . . . . . . . . 205
ctg.ini: CLIENT section . . . . . . . . . . 206
ctg.ini: SERVER section . . . . . . . . . . 207
ctg.ini: DRIVER section . . . . . . . . . . 208
The product library and related
literature . . . . . . . . . . . . . 211
CICS Transaction Gateway books . . . . . . .211
Sample configuration documents . . . . . . .211
Redbooks . . . . . . . . . . . . . . .211
Other Useful Books . . . . . . . . . . . 212
CICS Transaction Server publications . . . . 212
APPC-related publications . . . . . . . . 213
TCP62–related publications . . . . . . . . 213
Obtaining books from IBM . . . . . . . . . 213
Contents v

Accessibility features for CICS
Transaction Gateway . . . . . . . . 215
Installation . . . . . . . . . . . . . . 215
Documentation . . . . . . . . . . . . . 215
Configuration Tool accessibility . . . . . . . 215
Components . . . . . . . . . . . . . 215
Keys . . . . . . . . . . . . . . . 215
Customizing colors and fonts . . . . . . . 218
cicsterm . . . . . . . . . . . . . . . 218
vi CICS Transaction Gateway: UNIX and Linux Administration
Glossary . . . . . . . . . . . . . 221
Index . . . . . . . . . . . . . . . 237
Notices . . . . . . . . . . . . . . 243
Trademarks . . . . . . . . . . . . . . 244
Sending your comments to IBM . . . 247

About this book
“What’s new on the CICS
Transaction Gateway on the
UNIX and Linux platform” on
page ix
Chapter 1, “CICS Transaction
Gateway overview,” on page 1
Chapter 2, “Planning your
installation,” on page 19
Chapter 3, “Installing the CICS
Transaction Gateway,” on page
29
Chapter 4, “Setting up
communication with CICS
servers,” on page 37
Chapter 5, “Configuration,” on
page 49
Chapter 6, “Network Security,”
on page 95
Chapter 7, “Client security,” on
page 107
Chapter 8, “Performance,” on
page 113
Chapter 9, “Operating the CICS
Transaction Gateway,” on page
121
Chapter 10, “Operating the
Gateway daemon,” on page
123
Chapter 11, “Operating the
Client daemon,” on page 133
Chapter 13, “Problem
determination and problem
solving,” on page 153
Chapter 14, “Migration,” on
page 181
This book describes the planning, installation, configuration, and operation, of the
IBM ®
CICS ®
Transaction Gateway product.
You should be familiar with the operating system on which your CICS Transaction
Gateway runs, and also with Internet terminology.
Read this for information on functional changes made in this version of CICS
Transaction Gateway.
Read this for an overview of CICS Transaction Gateway and the functions it
provides.
Read this for information on planning your installation, including the hardware
and software you need to run CICS Transaction Gateway.
Read this for information on how to install CICS Transaction Gateway.
Read this for information on how to set up communication links between CICS
Transaction Gateway and CICS servers.
Read this for information on how to configure your CICS Transaction Gateway.
Read this for information on how to set up CICS Transaction Gateway to use the
SSLnetwork security protocol.
Read this for information on how to provide a user ID and password when
connecting to a CICS server.
Read this for information on how to tune your CICS Transaction Gateway, and
other system components, to achieve the best possible performance.
Read this for information on how to operate the CICS Transaction Gateway.
Read this for information on how to operate the Gateway daemon.
Read this for information on how to operate the Client daemon of CICS
Transaction Gateway.
Read this for information on problem determination and problem solving.
Read this if you are currently using an earlier version of CICS Transaction Gateway
or CICS Universal Client.
Statistics Read this for information about statistics that the CICS Transaction Gateway
provides.
© Copyright IBM Corp. 1996, 2006 vii

Installation path
The term is used in file paths to represent the directory where you
installed the product. The default location for new installations is:
UNIX ®
Linux ®
platforms
/opt/IBM/cicstg
platforms
/opt/ibm/cicstg
If you are upgrading, the installation process keeps your existing directory
structure.
viii CICS Transaction Gateway: UNIX and Linux Administration

What’s new on the CICS Transaction Gateway on the UNIX
and Linux platform
This edition replaces SC34-6372-01. Technical changes to the text are indicated by a
vertical line to the left of the change.
v Online statistics for real-time monitoring of CICS TG systems, enabling current
activity to be monitored proactively; see Chapter 15, “Statistics introduction,” on
page 185, and “Displaying statistics” on page 187.
v Support for Internet Protocol V6 (IPv6) connections from remote Java
clients,
providing for better routing, enhanced security, and global scalability delivered
in this latest version of the IP standard. This affects the “Bind Address” on page
60 configuration setting.
v Support for the Transport Layer Security (TLS) 1.0 protocol enabling more
stringent encryption capabilities and better interoperation with a variety of
secure clients; see “Transport Layer Security” on page 105.
v The CICS Transaction Gateway JCA resource adapters can be used in remote
mode from a WebSphere ®
Application Server running in a 64-bit runtime
environment; see “Java support for the resource adapters and Java Client
applications” on page 21.
v JVM and system configuration dumps are available; see “JVM and system
dumps” on page 161.
v A new configurable server idle timeout option to reduce network overheads of
many attached clients; see “Server idle timeout (mins)” on page 72.
v Extensions to Systems Network Architecture (SNA) support to include the Linux
on Intel ®
, Linux on POWER , and Sun Solaris environments, allowing you to
maintain your SNA infrastructure or migrate away from TCP62 environments;
see “SNA configuration” on page 41.
Removed and changed function
For information on removed and changed function, see “Migrating to Version 7”
on page 181.
© Copyright IBM Corp. 1996, 2006 ix

x CICS Transaction Gateway: UNIX and Linux Administration

Chapter 1. CICS Transaction Gateway overview
Figure 1. CICS Transaction Gateway
IBM CICS Transaction Gateway provides secure, easy access from Java Client
applications to CICS applications, using standard Internet protocols in a range of
configurations. It is a robust and scalable complement to a J2EE application server.
You can implement it as an e-business connector for IBM WebSphere Application
Server, which is a J2EE-compliant runtime environment for Java servlets and
enterprise beans. An API is provided that allows Java programmers to take
advantage of features provided in J2EE-compliant runtime environments.
CICS Transaction Gateway runs on a wide variety of operating systems. On
operating systems other than z/OS ® , CICS Transaction Gateway can access many
different types of CICS server. On z/OS, the CICS Transaction Gateway can access
only CICS Transaction Server for z/OS. See “Supported software” on page 19 for
information on supported operating systems and CICS servers.
On operating systems other than z/OS, CICS Transaction Gateway uses a Client
daemon to route External Call Interface (ECI), External Presentation Interface (EPI),
and External Security Interface (ESI) requests to a CICS server (see “The external
access interfaces (ECI, EPI, ESI)” on page 4). On z/OS, CICS Transaction Gateway
can route only ECI requests, and has no Client daemon.
Figure 1 shows how a web client can access CICS programs and data. Note that
the CICS Transaction Gateway is shown as installed on a J2EE application server
machine. This is necessary only if you are using the CICS Transaction Gateway
with Java applets or servlets.
Communication between CICS Transaction Gateway and the Client application
uses the following protocols:
v TCP/IP sockets
v Secure Sockets Layer (SSL)
© Copyright IBM Corp. 1996, 2006 1

TCP/IP sockets and SSL provide an efficient method of communication for intranet
applications.
CICS Transaction Gateway can manage many concurrent links to connected Web
browsers. It can also control asynchronous conversations to multiple CICS servers.
The multithreaded architecture of the CICS Transaction Gateway enables a single
Gateway to support multiple concurrently connected users.
CICS Transaction Gateway Version 7.0 scenarios
A number of parts, both internal and external to the CICS Transaction Gateway, are
used when creating a business solution using the product. Figure 2 shows some of
the possible scenarios, and the terminology used.
Figure 2. CICS Transaction Gateway uses, with their associated terminology
The following explains the terms used in Figure 2:
Gateway daemon
This is a long running Java process used only in remote mode. The
Gateway daemon listens for network requests from remote Java Client
applications. It issues these requests to CICS using the facilities of the
Client daemon on UNIX, Windows ®
and Linux platforms, or using the
EXCI on z/OS. The Gateway daemon runs the protocol listener threads,
the connection manager threads and the worker threads. It uses the
2 CICS Transaction Gateway: UNIX and Linux Administration

GATEWAY section of ctg.ini (and on z/OS the STDENV file or the
ctgenvvar script) for its configuration.
Client daemon
The Client daemon, process cclclnt, exists only on UNIX, Windows and
Linux. It manages network connections to CICS servers. It processes ECI,
EPI, and ESI requests, sending and receiving the appropriate flows from
the CICS server to satisfy the application requests. It uses the CLIENT
section of ctg.ini for its configuration.
Gateway classes
This is the Java class library used by Java Client applications to invoke
services in CICS.
External CICS Interface (EXCI)
An MVS ®
application programming interface provided by CICS
Transaction Server for z/OS that enables a non-CICS program to call a
CICS program and to pass and receive data by means of a COMMAREA.
The CICS application program is invoked as if linked-to by another CICS
application program. The EXCI is used as the communications interface by
the CICS Transaction Gateway for z/OS. Compare with External Call
Interface (ECI).
Client API
This is the interface used by Client applications to invoke services in CICS
using the facilities of the Client daemon. See External Call Interface,
External Presentation Interface and External Security Interface.
Client application
A user application written in a supported programming language, other
than Java, that uses the Client API.
Java Client application
A user application written in Java, including servlets and enterprise beans,
that uses the Gateway classes.
local mode
A term that describes the use of the CICS Transaction Gateway local
protocol. The Gateway daemon is not used in local mode.
remote mode
A term that describes the use of one of the supported CICS Transaction
Gateway network protocols to connect to the Gateway daemon. See
Gateway daemon.
What CICS Transaction Gateway provides
The CICS Transaction Gateway provides the following:
A Gateway daemon
The Gateway daemon communicates with CICS applications running on CICS
servers through ECI, EPI, or ESI. It is usually resident on a J2EE application server.
The Gateway classes
This Java library includes classes that:
v Provide Application Programming Interfaces (APIs) for ECI, EPI, and ESI.
This allows communication between Java Client applications and the Gateway
daemon.
Chapter 1. CICS Transaction Gateway overview 3

v Allow Java Client applications to communicate with transactions on a server and
handle 3270 data streams.
v Allow your Java Client applications to use the SSL network security protocol.
J2EE resource adapters
These provide a J2EE-compliant interface to CICS for your Java Client applications.
A Client daemon
The Client daemon can support concurrent, ECI, and EPI calls to one or more CICS
servers.
The Client daemon can communicate with multiple CICS servers using a variety of
protocols. See “Communication with CICS servers” on page 25. Support for a
protocol may be provided by one or more communication software products, so
you can use the products best suited to your network environment. See
“Supported software” on page 19.
The way that the Client daemon operates, and the servers and protocols used for
communication, are defined in the CICS Transaction Gateway initialization file.
You can use the Configuration Tool to define these settings. See Chapter 5,
“Configuration,” on page 49.
The external access interfaces (ECI, EPI, ESI)
An external interface allows non-CICS applications to access and update CICS
resources by calling CICS programs, or by initiating CICS transactions. When used
in conjunction with the CICS communication facilities, it enables non-CICS
programs to access and update resources on any CICS system. This supports such
activities as developing graphical user interface (GUI) front ends for CICS
applications, and allows the integration of CICS systems and non-CICS systems.
External Call Interface (ECI)
The ECI enables a user application to call a CICS program synchronously
or asynchronously. It enables the design of new applications to be
optimized for client/server operation, with the business logic on the server
and the presentation logic on the client.
External Presentation Interface (EPI)
The EPI enables a user application to act as a logical 3270 terminal and so
control a CICS 3270 application. It enables modern technologies, such as
graphical or multimedia interfaces, to be used with traditional CICS 3270
applications.
External Security Interface (ESI)
The ESI enables user applications to verify and change passwords for
specified user IDs that are managed by an external security manager (ESM)
on a CICS server.
For more information on the external access interfaces, see CICS Transaction
Gateway: Programming Guide and CICS Transaction Gateway: Programming Reference.
4 CICS Transaction Gateway: UNIX and Linux Administration

Additional functions
3270 terminal emulation (cicsterm)
CICS 3270 terminal emulation enables a CICS Transaction Gateway system to
function as a 3270 display for CICS applications, without needing a separate 3270
emulator product. Multiple CICS 3270 emulation sessions can run to one or more
CICS servers.
You can use mapping files to customize the client emulator’s screen color attributes
and keyboard settings, for example, to comply with company standard keyboard
layouts.
CICS Client terminal definitions are autoinstalled on the CICS server, and do not
have to be predefined.
3270 printer support (cicsprnt)
CICS 3270 printer support allows you to define a printer terminal on a CICS
Transaction Gateway system. This enables CICS applications running on a server to
send output to a printer attached to the CICS Transaction Gateway.
You can send output to a physical printer or you can specify a command to
process the data into a format more suitable for special-purpose printers.
CICS 3270 printer support uses CICS 3270 terminal emulation functions. See
Table 1 on page 25 for information on which CICS servers currently support CICS
3270 emulation and hence CICS 3270 client printer support.
Controlling the CICS Transaction Gateway
Commands are provided to:
v Control the Gateway daemon
You can:
– Specify the TCP/IP port on which the CICS Transaction Gateway listens.
– Specify the initial number and maximum number of ConnectionManager
threads
– Specify the initial number and maximum number of worker threads
– Enable standard tracing
– Disable the reading of input from the console
– Specify the file to which trace output is written
– Enable full debug tracing
– Specify the maximum size of the trace output file
– Specify the maximum size of any data blocks that are shown in the trace
– Enable the display of symbolic TCP/IP host names in messages
– Specify the offset from which displays of any data blocks start
– Enable Java exception stack tracing
– Pass an argument to the JVM
v Control the Client daemon
You can:
– Start or stop the client daemon
– Turn client trace on or off
– Specify the client components to be traced
– Set up security by specifying user IDs and passwords for a CICS server
– List connected servers
Chapter 1. CICS Transaction Gateway overview 5

Network security
– Enable and disable the display of messages
– Perform controlled restarts of the client daemon
v Control terminal emulation
You can:
– Start and stop the terminal emulator
– Specify the initial transaction
– Define the terminal characteristics
– Specify the name of the keyboard and screen color mapping files
– Define the command used to process print requests
– Specify the name of a file used for appending print requests
v Control client printer operation
You can:
– Start and stop the client printer emulator
– Specify the initial transaction to be run against the client printer
– Define the printer terminal characteristics
– Define the command used to process print requests
– Specify the name of a file used for appending print requests
Controlling the CICS Transaction Gateway dynamically
Using the ctgadmin script, you can:
v Set the trace for the Gateway daemon
v Set JNI trace
v Query trace options
v Shut down the CICS Transaction Gateway
CICS Transaction Gateway provides comprehensive support for secure
communication, which is critical to successful Internet operation. The secure
network protocol SSL allows your Client applications and Java Client applications,
to communicate securely with your CICS Transaction Gateway. Network security
and its implementation on CICS Transaction Gateway is discussed in detail in
Chapter 6, “Network Security,” on page 95; the following sections summarize the
functions provided by SSL.
The characteristics of secure communication are:
Confidentiality
Integrity
Accountability
6 CICS Transaction Gateway: UNIX and Linux Administration
The content of messages remains private as they pass over the Internet, or
your intranet.
Data exchanged between the client and the server is encrypted. Only your
client (your application or servlet) and your server (the CICS Transaction
Gateway) can make sense of the data.
Messages are not altered during transmission.
Integrity guarantees that the message you sent reaches the recipient intact.
Encryption and digital signatures ensure integrity.

Authenticity
The sender and the receiver both agree that the exchange took place.
Accountability settles any disputes over whether the message was sent and
received. Digital signatures ensure accountability, so that you can identify
who is responsible if something goes wrong.
You know who you are talking to and that you can trust that person.
Authenticity requires verification of identities, so that you can be sure that
others are who they say they are. Digital signatures and digital certificates
ensure authenticity.
CICS Transaction Gateway’s implementation of the SSL protocol provides
server authentication. This means that when a client establishes a connection
with CICS Transaction Gateway, it must authenticate the server’s details.
You can also enable client authentication. This means that the server will
authenticate the client’s details.
Encryption
Encryption ensures confidentiality in transmissions sent over the Internet. In its
simplest form, encryption is the scrambling of a message so that it cannot be read
until it is unscrambled later by the receiver. The sender uses an algorithmic
pattern, or key, to encrypt the message, and the receiver uses a decryption key to
unscramble the message.
Two kinds of key can be used for encryption:
Symmetric keys
The sender and receiver use the same key to encrypt and decrypt the
message. The risk with symmetric keys is that you need a safe
transportation method to use when sending your key to the people with
whom you want to communicate.
Asymmetric keys
These consists of a pair of keys: a public key and a private key. Unlike
symmetric keys, these are different from each other. The private key holds
more of the secret encryption pattern than the public key.
A sender sends its public key to anyone it wants to communicate with
securely. It retains the private key and protects it with a password. Only
the sender can decrypt a received message encrypted with its public key,
because only it has the private key.
Asymmetric key encryption is also known as public key encryption.
SSL uses both asymmetric and symmetric key encryption. It uses public key
(asymmetric) encryption as a safe way of sharing a symmetric key between server
and client. This symmetric key is then used to encrypt and decrypt all data
transferred on the SSL connection. This encryption protects the data from other
parties that try to eavesdrop and ensures that private information, such as credit
card numbers, can be transferred securely. See “Authentication using SSL” on page
9.
Digital signatures and digital certificates
A digital signature is a unique, mathematically computed, signature that ensures
accountability.
Chapter 1. CICS Transaction Gateway overview 7

A digital certificate allows unique identification of an entity; it is essentially an
electronic ID card, issued by a trusted third party. Digital certificates form part of
the ISO authentication framework, also known as the X.509 protocol. This framework
provides for authentication across networks.
A digital certificate serves two purposes: it establishes the owner’s identity, and it
makes the owner’s public key available. A digital certificate is issued by a certificate
authority (CA), for example VeriSign, or Thawte. It is issued for only a limited time,
and when its expiry date has passed, it must be replaced.
A digital certificate consists of:
v The public key of the person being certified
v The name and address of the person being certified, also known as the
Distinguished Name (DN)
v The digital signature of the CA
v The issue date
v The expiry date
The Distinguished Name is the name and address of a person or organization. You
enter your Distinguished Name as part of requesting a certificate. The
digitally-signed certificate includes not only your own Distinguished Name, but
the Distinguished Name of the CA, which allows verification of the CA.
To communicate securely, the receiver in a transmission must trust the CA that
issued the certificate that the sender is using. This means that when a sender signs
a message, the receiver must have the corresponding CA’s signer certificate and
public key designated as a trusted root key. For example, your Web browser has a
default list of signer certificates for trusted CAs. If you want to trust certificates
from another CA, you must receive a certificate from that CA and designate it as a
trusted root key.
If you send your digital certificate containing your public key to someone else,
what keeps that person from misusing your digital certificate and posing as you?
The answer is: your private key.
A digital certificate alone is not proof of anyone’s identity. The digital certificate
allows verification only of the owner’s identity, by providing the public key
needed to check the owner’s digital signature. Therefore, the digital certificate
owner must protect the private key that belongs with the public key in the digital
certificate. If the private key were stolen, anyone could pose as the legitimate
owner of the digital certificate.
Obtaining a digital certificate
CICS Transaction Gateway allows you to obtain digital certificates in two ways.
You can buy externally-signed certificates from a certificate authority (CA), or you
can establish yourself as a CA to allow you to issue self-signed X.509 certificates.
Externally-signed certificates are more suitable for Internet use, while self-signed
certificates might be suitable for internal use within an organization.
Buying a certificate from a certificate authority
If you plan to conduct commercial business on the Internet, buy a server certificate
from a certificate authority (CA) such as VeriSign or Thawte.
8 CICS Transaction Gateway: UNIX and Linux Administration

When you submit a certificate request to a CA, they require you to prove who you
are before they issue you a certificate. The approval process is necessary to protect
you, your organization, and the CA. The CA will digitally sign your certificate
request and return the unique certificate to you by e-mail.
Issuing certificates yourself
If you act as a CA, you can sign your own or anyone else’s certificate request. This
is a good choice if you need the certificates only within your own organization,
and not for external Internet commerce. You can choose to allow access to only a
carefully controlled group of key people within your intranet.
Your key people should have browsers that can receive your self-signed CA
certificate and designate it as a trusted root. They can then trust your
communications and share information safely.
See Chapter 6, “Network Security,” on page 95 for more information on obtaining
digital certificates.
Key rings and KeyStores
Digital certificates, public keys, private keys, and trusted root keys are kept in
special types of file that the security protocols can use. The Java Secure Socket
Extension (JSSE) implementation of the SSL protocol uses files called KeyStores.
See “Java Secure Socket Extension (JSSE)” on page 95 for information on how to
create key rings and KeyStores. The SSL protocol requires access to these files to
establish secure connections. See “Configuring CICS Transaction Gateway for SSL”
on page 106 for information on how to provide this access.
Authentication using SSL
SSL allows the client to authenticate the identity of the server. This is called server
authentication.
SSL Version 3 also allows the server to authenticate a client. This is called client
authentication, and is used if the server needs to check who a client is before
responding. If SSL client authentication is enabled, the server requests the client’s
certificate whenever the client makes an SSL connection. The server validates the
DN information in the client request against the DN information in the client’s
certificate before serving the document.
SSL uses public key (asymmetric) encryption for a security “handshake” when
establishing a TCP/IP connection between the client and the server. Figure 3 on
page 10 illustrates SSL handshaking with server authentication. During the
handshake, the client receives the server’s digital (X.509) certificate. The client
authenticates the server, using a list of known CAs. Also, if the client requests a
document protected by SSL client authentication, the server requests the client’s
certificate. The client then generates a random symmetric key and encrypts it using
server’s public key. SSL then uses the symmetric key to encrypt and decrypt all of
the information in both the client request and the server response, including:
v The URL the client is requesting
v The contents of any form being submitted
v Authentication information, such as user names and passwords
v All data sent between the client and the server
Chapter 1. CICS Transaction Gateway overview 9

Figure 3. SSL handshaking with server authentication
CICS Transaction Gateway supports the JSSE implementation of SSL. This is a Java
implementation that provides support for 128 bit encryption. JSSE as supplied with
the Java SDK is the only supported option. See Chapter 6, “Network Security,” on
page 95 for more information about migration.
Security exits
CICS Transaction Gateway provides exits that enable the user to define security
operations such as public key encryption. They can also be used for data
compression. Some example source files are provided in this directory:
The J2EE resource adapters
/samples/java/com/ibm/ctg/samples/security
You can also use the security exits to authenticate an X.509 client certificate when
client authentication is enabled.
For more information, refer to the CICS Transaction Gateway: Programming Guide.
An API in the CICS Transaction Gateway allows Java programmers to take
advantage of features provided in J2EE-compliant runtime environments (for
example IBM WebSphere Application Server). The J2EE connector architecture
(JCA) defines a standard for connecting the Java 2 Platform, Enterprise Edition
(J2EE) to heterogeneous Enterprise Information Systems (EIS) such as CICS. The
architecture defines a set of scalable, secure, and transactional mechanisms that
enable the integration of EISs with application servers and enterprise applications.
10 CICS Transaction Gateway: UNIX and Linux Administration

A proprietary J2EE application server, such as IBM WebSphere Application Server,
can be extended to support the resource adapter architecture, and is then assured
of a seamless connectivity to multiple EISs.
The JCA defines a Common Client Interface (CCI) for EIS access. The CCI defines a
client API for interacting with heterogeneous EISs. The JCA enables a vendor such
as IBM to provide a standard resource adapter to allow access to its product. This
resource adapter is deployed to an application server and provides connectivity
between the EIS, the application server, and the enterprise application.
The Programming using J2EE chapter in CICS Transaction Gateway: Programming
Guide describes the J2EE resource adapters. The chapter includes information on
the J2EE samples that are provided.
The samples.txt file, in the \samples subdirectory, provides
additional information on the J2EE sample programs.
Dynamic Logical Partitioning (DLPAR, AIX only)
Local mode explained
The CICS Transaction Gateway for AIX ®
is a DLPAR-safe application. This means
that it does not fail as a result of DLPAR operations. Its performance might suffer
when resources are removed, and it might not scale when new resources are
added, but the program still works as expected.
Note: The CICS Transaction Gateway does not manage I/O devices such as
network adapters. Before removing such devices dynamically, ensure that
they are no longer being used by the CICS Transaction Gateway, or any of
its underlying network components.
The CICS Transaction Gateway provides connectivity from a variety of platforms
to Transaction Server on z/OS, and other CICS servers on distributed platforms. To
maximize flexibility and performance, the CICS Transaction Gateway can be
customized and configured in many ways. Using local mode where applicable is
one of the most powerful ways to reduce complexity and increase performance,
and yet this option sometimes gets little attention. This topic:
v Explains what local mode is
v Details the benefits of using local mode
v Suggests when it might be most useful
v Lists some points to consider when deciding whether to use local mode
Local mode and remote mode
“CICS Transaction Gateway Version 7.0 scenarios” on page 2 shows some possible
configurations of the CICS Transaction Gateway. As can be seen from the diagram,
the terms remote and local refer to the location of the Gateway classes (the API and
JCA Connector) relative to the Gateway daemon and the Client daemon (on
distributed platforms), or the EXCI layer (on z/OS). The term local mode refers to
usage of the local protocol.
In remote mode, Gateway classes connect to the Gateway daemon over the
network, using either TCP/IP or SSL. The Gateway daemon can accept connections
from multiple instances of the Gateway classes, from multiple client systems.
Implementing this type of architecture for the CICS Transaction Gateway requires
Chapter 1. CICS Transaction Gateway overview 11

careful planning and tuning to ensure that the solution meets the requirements of
the system as a whole. This involves activities such as:
v Planning network capacity
v Ensuring that time-outs through out the solution synchronize correctly
v Ensuring that the various thread pools that could be used are all consistent
Local mode can be used if the CICS Transaction Gateway is on the same system
as the Java Client application that is using the Gateway classes.
In this mode, the Gateway classes communicate directly with the Client daemon
(on distributed platforms) or the EXCI layer. Costly calls to the network layer, and
the requirement to run the Gateway daemon process, that are both required in
remote mode, are not needed in local mode.
Benefits of local mode
Using local mode where applicable can bring numerous benefits to a solution;
these can include the following, depending on the specific architecture being
implemented.
Increased Performance
One of the biggest benefits of local mode is the increased performance through the
CICS Transaction Gateway that it can provide, compared to remote mode. Local
mode does not use the network to pass requests to the Gateway daemon; the
Gateway daemon classes are already available to the Java virtual machine (JVM),
and can be used direct.
12 CICS Transaction Gateway: UNIX and Linux Administration

Figure 4. Additional overhead in remote mode
Figure 4 shows the additional overhead needed to make a call in remote mode
compared to local mode. Local mode saves processor cycles because the following
activities are not performed:
Chapter 1. CICS Transaction Gateway overview 13

Figure 5. Remote mode
v Making calls to open connections to a remote host
v Performing a handshake with the remote Gateway daemon
v Tidying and closing the connection when the call is complete
Even the overhead of making the call is reduced, because in local mode there is no
dependency on the network, which is typically a large cost of any remote mode
call.
Using connection pooling in remote mode can reduce the overheads associated
with establishing connections. However, because remote mode requires network
flows, performance is not as good as when local mode is used.
Reduced complexity
Using local mode can make the overall system less complex. This in turn can help
to remove points of failure, cut administration and maintenance costs, and make
problem determination easier.
Figure 5 shows a typical 3-tier system, with Web clients connecting to a cluster of
four WebSphere Application Server nodes on z/OS. The nodes connect to two
Gateway daemons, also running on the same LPAR, and using TCP/IP port
sharing to balance the work between them. These then connect into the same CICS
region through EXCI. In remote mode, the WebSphere nodes use TCP/IP to flow
requests, although they are on the same LPAR as the Gateway daemons.
14 CICS Transaction Gateway: UNIX and Linux Administration

Figure 6. Local mode
Figure 6 shows a much simpler picture. Each WebSphere node now has a direct
route into CICS TS, through the CICS TG and the EXCI layer.
v Removing the Gateway daemon on CICS TG servers means two fewer address
spaces to configure, manage and maintain, and fewer system resources used.
v Doubling the number of EXCI pipes available (in the z/OS example shown)
increases the scalability of the system. To achieve this in remote mode, you
would have to increase the number of CICS TG address spaces to 4.
v Removing the network layer increases performance.
The same principle can be applied to a distributed environment, to similar effect.
Reduced use of system resources
By removing the need for the Gateway daemon, and possibly even an entire tier in
a solution, the amount of system resources required for that solution is reduced.
Removing the Gateway daemon eliminates an entire JVM from the picture, and
with it the extra threads, memory and CPU time required. Network-related
resources are also freed up. For example, limited resources such as network
bandwidth and sockets are no longer taken up managing connections between the
Java Client application and the Gateway daemon.
Easier configuration
The Gateway daemon component has several configuration options associated with
it, including:
v Which protocol to use
Chapter 1. CICS Transaction Gateway overview 15

v Security settings for SSL
v The number of threads in various pools
v Time-outs and other basic configurations settings
In particular, the thread pools and time-outs should be tuned to match the specific
solution being used. For example, how many connection manager threads should
be available, how many worker threads, what should the idle and connection
time-outs be? Each of those parameters can be affected by other components in the
solution.
v Connection managers can be affected by the number of remote clients, how often
they connect, and how quickly they reconnect in the event of a network failure.
v The number of worker threads can be affected by the number of threads
configured in WebSphere Application Server, the maximum concurrent work
expected (or allowed), and on z/OS how many CICS regions are being
connected to.
v Time-outs might have to tie up with time-outs in WebSphere Application Server,
CICS, or the network.
In local mode, settings directly related to the Gateway daemon are not used. There
are no thread pools or associated time-outs to configure. Requests are passed
directly from the Gateway classes to the Client daemon or EXCI. Of course, this
does not completely remove the need for configuration and tuning, at the same
time by removing a level of complexity, that configuration and tuning becomes
much simpler.
Benefits of remote mode
The benefits of remote mode include the following:
v You can present a single entry point to multiple Gateway daemons. All Java
Client applications talk to the same IP address.
Figure 7. Remote mode in z/OS, using TCP/IP load balancing
v On the z/OS operating system, TCP/IP load balancing can improve quality of
service.
v Remote mode enables two-phase commit to be used from a distributed
WebSphere Application Server.
v Spreading the load across multiple address spaces can improve performance.
16 CICS Transaction Gateway: UNIX and Linux Administration

Considerations when deciding whether to use local mode
Be aware of the following factors when deciding whether to use local mode.
Tracing
Because there is no Gateway daemon in local mode, the ability to enable and
disable tracing dynamically provided with CICS Transaction Gateway is no longer
applicable. Tracing is still available; to enable tracing in local mode, pass the
appropriate system properties to the WebSphere Application Server JVM. Consult
the documentation supplied with WebSphere Application Server for details of how
to do this.
Enabling local mode
The way in which local mode is enabled varies from application to application. It
can be done without a code change in most circumstances, and almost always
when using JCA. It simply requires the ConnectionURL, which defines where the
Gateway daemon is located, to be changed to local:. Where this is done depends
on the application.
1. JCA Connector - In the WebSphere Administration console, change the
ConnectionURL in the Custom Properties for your J2C Connection Factory to
local:
2. Java Client applications Simply change the connection URL used by the
JavaGateway object from the remote URL to local: . This can be done either by
passing the URL directly to the JavaGateway constructor, or by using the
setURL method of the JavaGateway object.
Change this:
javaGatewayObject = new JavaGateway( tcp://127.0.0.1 , 2006);
To this:
javaGatewayObject = new JavaGateway( local: , 0);
The port will be ignored.
Chapter 1. CICS Transaction Gateway overview 17

18 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 2. Planning your installation
This information helps you to plan the installation of the CICS Transaction
Gateway by listing the hardware and software that you need. The CICS servers to
which CICS Transaction Gateway can connect are also listed.
If you are using an earlier version of the product, or a CICS Universal Client, see
Chapter 14, “Migration,” on page 181 for a discussion of migration issues.
See the product readme file for any late changes to hardware and software
requirements.
v If you are installing from CD, the readme file is in the root directory:
Operating system README file
AIX README.AIX
HP-UX README.HPUX
Linux on Intel README.LNX
Linux on POWER README.pLNX
Linux on zSeries ®
Hardware requirements
Supported software
README.zLNX
Solaris README.SOL
v If you downloaded the product, the packaged file that you downloaded contains
the product code and the readme file for your operating system.
When you install the CICS Transaction Gateway, the file is copied into your
installation directory as readme.txt.
v An IBM eServer
zSeries system, or S/390 ®
system supported by Linux
v An Intel 32-bit system supported by Linux
v An IBM eServer pSeries ® , iSeries
or Open Power
system supported by Linux
v An IBM eServer pSeries system supported by AIX
v A Sun SPARC system supported by Sun Solaris
v An HP PA-RISC 1.1 or 2.0 system supported by HP-UX
For the latest details about supported software, visit the Web site at
http://www.ibm.com/support/docview.wss?uid=swg21239203 and follow the
Support link.
The CICS Transaction Gateway is supported with the following products:
Operating systems
The CICS Transaction Gateway is supported on the following operating systems:
v AIX V5.2. CICS Transaction Gateway is supported as a 32-bit application on both
32-bit and 64-bit kernels.
© Copyright IBM Corp. 1996, 2006 19

v AIX V5.3. CICS Transaction Gateway is supported as a 32-bit application on both
32-bit and 64-bit kernels.
v Linux on Intel - SUSE Linux Enterprise Server 9, with SP2 minimum service
level. CICS Transaction Gateway is supported as a 32-bit application on the
32-bit kernel. Linux distributions that use OEM code from SUSE are also
supported.
v Linux on Intel - SUSE Linux Enterprise Server 10. CICS Transaction Gateway is
supported as a 32-bit application on the 32-bit kernel.
v Linux on Intel - SUSE Linux Enterprise Desktop 10.
v Linux on Intel - Red Hat Enterprise Linux V3 with a minimum service level of
Update 6. CICS Transaction Gateway is supported as a 32-bit application on the
32-bit kernel. Only the NPTL threading model is supported.
v Linux on Intel - Red Hat Enterprise Linux V4 with a minimum service level of
Update 2. CICS Transaction Gateway is supported as a 32-bit application on the
32-bit kernel.
v Linux on POWER - SUSE Linux Enterprise Server V9. Linux distributions that
use OEM code from SUSE are also supported. CICS Transaction Gateway is
supported as a 32-bit application on the 64-bit kernel.
v Linux on POWER - SUSE Linux Enterprise Server V10. CICS Transaction
Gateway is supported as a 32-bit application on the 64-bit kernel.
v Linux on POWER - Red Hat Enterprise Linux V3 with a minimum service level
of Update 6. Only the NPTL threading model is supported. CICS Transaction
Gateway is supported as a 32-bit application on the 64-bit kernel.
v Linux on POWER - Red Hat Enterprise Linux V4 with a minimum service level
of Update 4. CICS Transaction Gateway is supported as a 32-bit application on
the 64-bit kernel.
v Linux on zSeries - SUSE Linux Enterprise Server V9. Linux distributions that use
OEM code from SUSE are also supported. CICS Transaction Gateway is
supported as a 32-bit application on the 64-bit kernel.
v Linux on zSeries - SUSE Linux Enterprise Server V10. CICS Transaction Gateway
is supported as a 32-bit application on the 64-bit kernel.
v Linux on zSeries - Red Hat Enterprise Linux V3 with a minimum service level of
Update 6. Only the NPTL threading model is supported. CICS Transaction
Gateway is supported as a 31-bit application on the 31-bit kernel.
v Linux on zSeries - Red Hat Enterprise Linux V4. CICS Transaction Gateway is
supported as a 32-bit application on the 64-bit kernel.
v Solaris V9. CICS Transaction Gateway is supported as a 32-bit application on
both 32-bit and 64-bit kernels. Only SPARC hardware is supported.
v Solaris V10. CICS Transaction Gateway is supported as a 32-bit application on
both 32-bit and 64-bit kernels. Only SPARC hardware is supported.
v HP-UX 11i v2. CICS Transaction Gateway is supported as a 32-bit application on
both 32-bit and 64-bit kernels. Only PA-RISC hardware is supported.
The CICS Transaction Gateway is a 32-bit application, and so can run on a 32-bit
operating system, or on 64-bit operating system that can natively run 32-bit
applications. Where available, both NPTL and LT threading models are supported
unless otherwise stated; NPTL is preferred.
All UNIX and Linux operating systems require the Korn shell to be installed, so
that scripts supplied with the product can run.
20 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Web browsers
v HTML functions: Any browser that supports HTML V1.0 should work with the
product.
v Java Functions: Any Java 1.5 compliant Web browser should work with the
product.
Note: Java applets are supported for compatibility with previous versions of the
CICS Transaction Gateway. However, support for them might be removed in
a future release. It is recommended that you use Java applications, or Java
servlets, when developing new solutions.
Java support for the Gateway daemon
The CICS Transaction Gateway supports the following Java runtime environments.
Service Release 3 is the minimum service level required. It is recommended that
the latest Service Release level is used.
v AIX: IBM 32-bit Runtime Environment for AIX, Java 2 Technology Edition,
Version 5
v Linux on Intel: IBM 32-bit Runtime Environment for Linux on Intel architecture,
Java 2 Technology Edition, Version 5
v Linux on POWER: IBM 32-bit Runtime Environment for Linux on iSeries and
pSeries, Java 2 Technology Edition, Version 5
v Linux on zSeries: IBM 31-bit Runtime Environment for Linux on zSeries
architecture, Java 2 Technology Edition, Version 5
v HP-UX: HP 32-bit Runtime Environment for J2SE HP-UX 11i platform, adapted
by IBM for IBM software, Version 5
v Solaris: IBM 32-bit Runtime Environment for Solaris, Java 2 Technology Edition,
Version 5
Java support for the resource adapters and Java Client
applications
The CICS Transaction Gateway supports the following Java software development
kits and runtime environments for use with Java Client applications. Service
Release 3 is the minimum service level required. It is recommended that the latest
Service Release level is used.
v IBM 32-bit SDK for AIX, Java 2 Technology Edition, Version 5
v IBM 32-bit SDK for Linux on Intel architecture, Java 2 Technology Edition,
Version 5
v IBM 32-bit SDK for Linux on iSeries and pSeries, Java 2 Technology Edition,
Version 5
v IBM 31-bit SDK for Linux on zSeries architecture, Java 2 Technology Edition,
Version 5
v HP 32-bit SDK for J2SE HP-UX 11i platform, adapted by IBM for IBM Software,
Version 5
v IBM 32-bit SDK for Solaris, Java 2 Technology Edition, Version 5
v IBM 32-bit SDK for Windows, Java 2 Technology Edition, Version 5
v IBM 31-bit SDK for z/OS, Java 2 Technology Edition, Version 5
The following Java runtime environments are supported only under WebSphere
Application Server v6.1 or later, for connectivity to a remote Gateway daemon.
v IBM 64-bit SDK for AIX, Java 2 Technology Edition, Version 5
Chapter 2. Planning your installation 21

|
|
|
|
|
|
|
|
|
|
|
JSSE
v IBM 64-bit SDK for Linux on AMD64/EM64T architecture, Java 2 Technology
Edition, Version 5
v IBM 64-bit SDK for Linux on iSeries and pSeries, Java 2 Technology Edition,
Version 5
v IBM 64-bit SDK for Linux on zSeries architecture, Java 2 Technology Edition,
Version 5
v IBM 64-bit SDK for Windows, Java 2 Technology Edition, Version 5
v IBM 64-bit SDK for z/OS, Java 2 Technology Edition, Version 5
v IBM 64-bit SDK for z/OS, Java 2 Technology Edition, Version 5 with the CICS
Transaction Gateway in local mode running in WebSphere Application Server
v6.1
JSSE support is provided by the relevant supported Java SDK, or by WebSphere
Application Server. The CICS Transaction Gateway does not support the use of
JSSE with applets.
CICS servers
The CICS Transaction Gateway is supported with the following CICS servers:
v CICS Transaction Server for z/OS V2.2
– Apply APAR PQ92943 and PK17427 for EXCI
– Apply APAR PK08496 for mixed-case password support.
– If connecting over TCP/IP, you are recommended to apply APAR PQ75803
and PQ82124.
– Apply APAR PQ70543 for better recovery for EPI and cicsterm requests made
over SNA, after a failure of CICS or the network.
v CICS Transaction Server for z/OS V2.3
– Apply APAR PQ92943 and PK17427 for EXCI.
– Apply APAR PK08496 for mixed-case password support.
– If connecting over TCP/IP, you are recommended to apply APAR PQ81772
and PQ82124.
v CICS Transaction Server for z/OS V3.1. Apply APAR PK17426 for EXCI.
v CICS/VSE 2.3
– Apply APAR PQ30169 for EPI support.
v CICS Transaction Server for VSE/ESA
1.1.1
– If connecting over TCP/IP, you are recommended to apply APAR PQ80212
and APAR PQ52342.
– Apply APAR PQ30170 for EPI support.
v TXSeries ®
V5.1 (Windows, AIX, Solaris, HP-UX)
v TXSeries V6 (Windows, AIX, Solaris, Linux on Intel PRPQ)
v CICS Transaction Server for Windows V5.0
v CICS Transaction Server for iSeries V5.1, V5.2 and V5.3
J2EE application servers
The resource adapters supplied with the CICS TG are supported with the
following J2EE application servers:
v IBM WebSphere Application Server V6.1.
22 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
In remote mode, earlier versions of the CICS TG resource adapters can be used to
connect to the current version of the CICS TG. To do this you must use a version
of the CICS TG resource adapter that is supported with the J2EE application server
in question. In local mode, the resource adapters and CICS TG must be at the same
level.
WebSphere Application Server V6
As a migration aid for existing customer applications, the supplied CICS
Transaction Gateway base classes are supported within the Web container in
WebSphere Application Server V6.1 with the following limitations:
v The base classes (JavaGateway, ECIRequest, ESIRequest) are currently supported
for compatibility reasons. Support for the base classes under WebSphere
Application Server might be removed in a future release.
v All ECI requests must be non-transactional. This means that only the field
ECI_NO_EXTEND is supported on the ECIRequest constructor as the
Extend_Mode.
v All ECI requests must be synchronous, that is only the fields ECI_SYNC or
ECI_SYNC_TPN are supported as the call types.
v The EPIRequest class is not supported with WebSphere Application Server. Use
the EPI support classes (Terminal, Screen, and Field) instead.
SNA communications
Customers wishing to use SNA communications should install one of the following
products:
AIX
IBM Communications Server V6.3 for AIX.
Linux on zSeries
IBM Communications Server for Linux V6.2.
Linux on POWER
IBM Communications Server for Linux V6.2.
Linux on Intel
IBM Communications Server for Linux V6.2.
Solaris
SNAP-IX V7 for Solaris.
SNA communications connections are not available when using other UNIX and
Linux operating systems.
TCP/IP communications
TCP/IP support is provided by the operating system.
TCP62 communications
TCP62 support is provided by the CICS Transaction Gateway.
Compilers and application development tools
The CICS Transaction Gateway is supported with the following compilers and
application development tools:
AIX
v IBM VisualAge ®
C++ Professional V6.0
v IBM C for AIX V6.0
Chapter 2. Planning your installation 23

Other tools
v XL C/C++ Enterprise Edition 7.0 for AIX
v XL C/C++ Enterprise Edition 8.0 for AIX
HP-UX
v HP ANSI C
v HP aC++
Linux on Intel
v GNU C/C++ compiler (gcc) 3.2, 3.3, and 3.4
Linux on POWER
v GNU C/C++ compiler (gcc) 3.2, 3.3, and 3.4
v XL C/C++ Advanced Edition V7.0 and V8.0 for Linux
Linux on zSeries
v GNU C/C++ compiler (gcc) 3.2, 3.3, and 3.4
Solaris
Sun ONE Studio 9, 10, and 11
v Adobe Acrobat Reader 6.0
GPL licence and copyright issues on Linux
This product uses the following libraries from the glibc package: libnsl.so, libm.so,
libdl.so, ld.so, libc.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: Your use of the libstdc++ or egcs-c++ packages is subject to the
GNU GPL licence terms which could require you to provide source code in certain
circumstances. Note that IBM will not supply source code, for example for the
CICS Gateways C++ libraries.
CICS server PTF requirements
See the README file for the latest details on APARs and PTFs applicable to the
CICS Transaction Gateway.
Terminal Sign-on capability
CICS servers require APAR fixes to support the terminal sign-on capability
function available in this release; see “Supported software” on page 19 for details
of the APAR relating to your CICS server. If the server does not have the required
APAR applied and the ’-a’ option is not specified when the cicsterm command is
issued, the installed terminal will give unpredictable results.
Timeout support
Any TXSeries or CICS Transaction Server on the Windows and UNIX operating
systems must include the appropriate PTF level to provide complete support for
timeouts. See “Supported software” on page 19 for details.
24 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
If the server does not have the required APAR applied and the ’-a’ option is not
specified when the cicsterm command is issued, the CTIN transaction abends with
code A42B. You see the following:
v The CICS Transaction Gateway displays the message: CCL7053E Errors found
while communicating with server
v This message is written to cicscli.log:
CCL3105 Inbound CICS data stream error (CTIN,4, 0)
v On the server, the message: ERZ042004E/0112: An invalid request was received
from client is written to CSMT.out
v console.msg includes this: ERZ014016E/0036: Transaction CTIN Abend A42B
Communication with CICS servers
You can use these protocols to communicate with CICS servers:
TCP/IP
TCP/IP is a widely used, robust, suite of protocols, particularly important
in connecting heterogeneous networks.
SNA The CICS Transaction Gateway uses Advanced Program-to-Program
Communication (APPC) to provide SNA LU 6.2 communication. APPC is
an implementation of the SNA LU 6.2 protocol that provides
device-independent application-to-application communication over LU 6.2
sessions.
TCP62 TCP62 is a communications mechanism that allows connections from a
CICS Transaction Gateway to a Transaction Server for z/OS region over an
IP network. It uses IBM’s Multiprotocol Transport Networking (MPTN)
protocol switching technology to send LU6.2 SNA flows over an IP
network.
The protocols that you can use for the various client/server connections are shown
in Table 1. This table lists the protocols that you can use to connect your CICS
Transaction Gateway to your CICS server. It also shows whether EPI emulation
and ECI are supported for your combination of CICS server and CICS Transaction
Gateway operating system.
Table 1. Protocols and functions supported. If a protocol or feature is supported by the CICS Transaction Gateway
only on certain operating systems, the operating systems are listed. * means that the protocol or feature is
supported; V means that it is not supported.
SERVER TCP/IP SNA TCP62 ECI
EPI
See note ESI
CICS Transaction
Server for z/OS V2.2,
V2.3, and V3.1
CICS Transaction
Server for VSE/ESA
V1.1.1
CICS/VSE ®
* (ECI only)
* (ECI only)
V2.3 V
AIX
Linux
Solaris
AIX
Linux
Solaris
AIX
Linux
Solaris
* * * *
V * * *
V * * *
TXSeries V5, V5.1 * V V * * V
CICS Transaction
Server for Windows
V5.0
* V V * * V
Chapter 2. Planning your installation 25

|
|
|
|
Table 1. Protocols and functions supported (continued). If a protocol or feature is supported by the CICS Transaction
Gateway only on certain operating systems, the operating systems are listed. * means that the protocol or feature is
supported; V means that it is not supported.
SERVER TCP/IP SNA TCP62 ECI
CICS Transaction
Server for iSeries V5.1
CICS Transaction
Server for iSeries V5.2
and V5.3
V
*
AIX
Linux
Solaris
AIX
Linux
Solaris
EPI
See note ESI
* * * *
* * * *
Note: EPI also incorporates CICS 3270 terminal emulation and CICS 3270 client
printer support.
Restrictions on CICS Transaction Server for iSeries
The following restrictions apply:
v DBCS languages are supported when communicating using ECI but NOT EPI.
v Sign-on capable terminals are not supported.
v You cannot start the CEDA transaction from a client terminal.
v You cannot use PF1 to get CICS online help from a client terminal.
Why use a particular protocol?
As shown in table Table 1 on page 25, some protocols can be used only for certain
types of client/server connection. Access to 3270-based CICS transactions might
require SNA or TCP62 connections. SNA network connections are the
recommended approach because they can be routed over IP networks using the
DBCS multibyte characters
SNA Remote API Client or Enterprise Extender functionality, and do not require
complex AnyNet ®
definitions.
For information on configuring TCP62, see “TCP62 configuration” on page 39. For
information on continuing AnyNet support in z/OS Communications Server, refer
to the information in the z/OS Statements of direction announcement, Software
Announcement 203-266, dated October 7, 2003; and the z/OS V1.7 preview
announcement, Software Announcement 205-034, dated February 15, 2005.
Some characters in certain code pages are represented with 3 or more bytes. The
CICS Transaction Gateway does not support multibyte characters that are longer
than 2 bytes. If you try to display such characters on a CICS terminal, you will get
unpredictable results.
If you are running on a locale that is unique to AIX or Solaris, you might
experience problems when connecting to certain CICS servers. The table below lists
the relevant client/server combinations.
CICS Client code page CICS Server operating
system
ja_JP (33722) OS/2 ®
ja_JP (33722) Windows NT ®
26 CICS Transaction Gateway: UNIX and Linux Administration
CICS Server code page
932
932

Server code page support
CICS Client code page CICS Server operating
system
ja_JP (33722) AIX 932
ko_KR (970) OS/2 949
ko_KR (970) Windows 949
zh_TW (964) OS/2 950
zh_TW (964) AIX 950
zh_CN (1383) OS/2 1381
zh_CN (1383) Windows NT 1381
CICS Server code page
Some CICS servers do not support all the code pages that are supported by the
operating system on which the CICS Transaction Gateway is running.
If the code page of an ECI application is different from the code page of the server,
data conversion must be performed at the CICS server. This applies for EBCDIC
CICS servers such as CICS Transaction Server for z/OS. For more information, see
Appendix A, “Data conversion when using the Client daemon and a CICS server,”
on page 193, the CICS server documentation, and the Redbook Java Connectors for
CICS.
Chapter 2. Planning your installation 27

28 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 3. Installing the CICS Transaction Gateway
Choosing what to install
This information describes how to install the CICS Transaction Gateway
You can choose either a complete or custom installation.
Complete installation
Installs all features:
v Program files
v Development kit, consisting of the following features:
– Programming samples (installed to /samples/)
– Toolkit (includes Javadoc information)
into the default installation directory (see “Installation path” on page viii).
Custom installation
v Select the features to install
Before you install the CICS Transaction Gateway
1. Check that your operating system is supported; see “Supported software” on
page 19 for supported operating systems. The product will not install if the
version of the operating system is below that supported.
2. Log on as root.
3. Linux operating systems: if the system default does not allow other users to
read and execute files that root has created, issue the following command from
the command line:
umask 022
4. Close down any programs that are running, including the following:
v Client daemon (issue the cicscli -x command)
v Gateway daemon
v Configuration Tool
5. The installation process can upgrade from the CICS Transaction Gateway V5 or
later. Remove any other versions of the CICS Transaction Gateway and CICS
Universal Client before installing this product. Remove any beta versions of the
product.
Known issues
v On the Linux on Intel platform, if a folder created during installation cannot be
removed by the uninstallation program, a warning might be displayed. This
warning will be issued if the folder contains a file that has been modified or is
new, for example ctg.ini. This warning can be ignored.
v On the HP-UX platform, if an installation or uninstallation is cancelled midway
through execution, exceptions might be thrown reporting missing files from the
com.sun.java.swing.plaf.motif.MotifLookAndFeel package. For example,
com.sun.java.swing.plaf.motif.MotifLookAndFeel/icons/UpFolder.gif not
found. These can be ignored.
© Copyright IBM Corp. 1996, 2006 29

v On the HP-UX platform, when creating a response file for installation or
uninstallation, formatting errors might be displayed. For example, ″Error
formatting options file entry (starting with ″This file contains v...″): Illegal
character ″8″ in encoding name.″ These can be ignored.
Installing with the InstallShield wizard
Installing from the console
Follow these steps to install the CICS Transaction Gateway:
1. Insert CD1 into the drive. If installing from a network drive, connect to the
drive.
2. Issue a command like the following: ///installer, where
is the name of your mounted cd drive and is your
operating system.
3. A welcome screen is displayed. Click Next.
4. If you are upgrading, you see the Upgrade warning screen. Click Next to
continue.
5. The license agreement is displayed. Read the agreements, click the appropriate
radio button, and then click Next. You must accept all license agreements that
are shown to continue the installation. License files are stored in the
/license subdirectory. If you run a console-based installation in
a DBCS locale, the License agreement is displayed in English, and not the
local language. Installation using a Graphical User Interface is not affected.
6. The README file is displayed, giving details of any late changes to the
product. Read it and then click Next.
7. Choose the type of installation required. Select Complete or Custom as
appropriate, and then click Next.
If you chose a complete installation, go to step 9. If you chose a custom
installation, continue at step 8.
8. A screen showing the features that can be installed is displayed. Select the
check box for each feature that you want to install.
9. (Resume here if you chose a complete installation in step 7.) Information
about the choices you have made is displayed on screen. Read this and then
click Next to start installing. The installation process keeps you informed of
progress.
10. Read the information about configuring the product and click Finish to end
the installation process.
To install from the command line, take the following steps:
1. Insert CD1 into the drive. If installing from a network drive, connect to the
drive.
2. Issue a command like the following:
///installer -console
where is the name of your mounted cd drive and is your
operating system.
You cannot cancel a command line installation after the installer has started to
copy files.
30 CICS Transaction Gateway: UNIX and Linux Administration

Installing silently
You can use a silent installation to install the CICS Transaction Gateway without
going through any of the installer screens. The installation process takes its input
from a response file; no user input is required. If you do not provide a response
file, all default options are used.
Creating a response file
Use one of the following methods to create a response file:
v Use the supplied sample file installResponseSamp.txt. Edit this file as
appropriate.
v Create a response file by installing the CICS Transaction Gateway and recording
the responses that you enter. Issue the following command:
installer -options-record response_file_name
This stores your responses in file response_file_name. Note that there is no
space between -options and -record.
Using the response file to install silently
To install silently, take the following steps:
1. Make the response file and the install image available to computer on which
the CICS Transaction Gateway is to be installed.
2. Issue the following command:
installer -options "response_file_name" -silent
Installing silently with no response file
To install silently without using a response file, issue the following command:
Actions after installation
installer -silent -V licenseAccepted=true
All options will use default values.
Install the Java runtime environment
You need Java to run the Gateway daemon, and the Configuration Tool. You do
not need it to run only the Client daemon.
Install the JRE at the following location:
//JRE/
where is the name of the mounted CD drive that contains CD2, and
is the name of your operating system.
Installing a shared library on Red Hat Enterprise Linux V3
Shared library /usr/lib/libstdc++-libc6.2-2.so.3 is not installed by default for Red
Hat Enterprise Linux (RHEL) 3.0, but is required by the run-time environment. The
CICS Transaction Gateway will not work correctly without it. The rpm that
contains this library is compat-libstdc++-7.3-2.96.122.i386.rpm. To install the library,
at a shell prompt type:
rpm -ivh compat-libstdc++-7.3-2.96.122.i386.rpm
Chapter 3. Installing the CICS Transaction Gateway 31

Adding features after installation
Removing features
1. Follow the steps in “Installing with the InstallShield wizard” on page 30 as far
as step 7 on page 30.
2. Select Custom as the type of installation, and select the features that you want
to install.
3. Complete the remaining steps in the installation process to add the new
features.
1. Run /bin/ctguninst
2. Click Next on the Welcome screen.
3. The uninstaller screen is displayed, with all features selected. Leave selected the
features that you want to remove; deselect any features that you want to keep.
Click Next.
4. Read the summary information and then click Next to remove the features.
5. Click Finish when prompted.
Updating the CICS Transaction Gateway
After installing the CICS Transaction Gateway, you can update the product, or
obtain corrective service software (“fixes”).
For information about corrective service software, visit the Web site at
www.ibm.com/software/cics/ctg and follow the Support link.
Uninstalling the CICS Transaction Gateway
To uninstall the CICS Transaction Gateway, run the ctguninst script.
Uninstalling from the console
Issue the following command:
ctguninst -console
Uninstalling silently
Issue the following command:
ctguninst [-options "response_file_name"] -silent
You do not have to provide a response file. If you do not, the whole product is
uninstalled.
Installation and uninstallation logs
Errors and warnings generated during the installation or uninstallation of the CICS
Transaction Gateway are recorded in the appropriate log file. The log files, if
created, are at the following locations:
Installation
/tmp/cicstgInstall.log
Uninstallation
/tmp/cicstgUninstall.log
32 CICS Transaction Gateway: UNIX and Linux Administration

National language support
If a log file already exists any new messages are appended to the end of the file.
Use the log to diagnose any problems that might have caused an installation or
uninstallation to fail, especially in silent mode where there is no user interaction
with the program.
After installation, you can change the language in which user messages are
displayed by entering the ctgmsgs command. To do this:
1. Stop the CICS Transaction Gateway.
2. Change the locale of the machine to the locale in which messages are to be
displayed.
3. Run the ctgmsgs command:
ctgmsgs XX
where XX is the two character message language. To obtain a list of available
languages, enter the command without parameters. Figure 8 shows the output:
This utility is used to change the language of user messages.
-------------------------------------------------------------
Language Locale Code Set
--------------------- -------------- ----------
en US English en_US ISO-8859-1
EN_US UTF-8
fr French fr_FR ISO-8859-1
FR_FR UTF-8
de German de_DE ISO-8859-1
DE_DE UTF-8
it Italian it_IT ISO-8859-1
IT_IT UTF-8
es Spanish es_ES ISO-8859-1
ES_ES UTF-8
tr Turkish tr_TR ISO-8859-9
TR_TR UTF-8
ja Japanese ja_JP EUCJP
JA_JP UTF-8
ko Korean ko_KR EUCKR
KO_KR UTF-8
zh Simplified Chinese zh_CN EUCCN
Figure 8. Output from the ctgmsgs command
This also shows the locale and code set associated with the language.
4. Restart the CICS Transaction Gateway.
Using an alternative code set on AIX
On AIX issue the command smitty iconv to use an alternate code set.
This provides the Convert Flat File screen, on which you can enter parameters:
Chapter 3. Installing the CICS Transaction Gateway 33

Convert Flat File
Type or select values in entry fields.
Press Enter AFTER making all desired changes.
[Entry Fields]
* CURRENT FILE / DIRECTORY name []
* CURRENT CODE set [] +
* NEW FILE / DIRECTORY name []
* NEW CODE set [] +
F1=Help F2=Refresh F3=Cancel F4=List
Esc+5=Reset F6=Command F7=Edit F8=Image
F9=Shell F10=Exit Enter=Do
Fill in this screen as follows:
CURRENT FILE / DIRECTORY name
Enter /bin/cclmsg.txt
CURRENT CODE set
Enter the code set for the language you selected with ctgmsgs.
NEW FILE / DIRECTORY name
Enter the name of the new file.
NEW CODE set
Enter the alternative code set. You can view a list of the alternative code
sets using the smitty lang command, which is used to set the language
environment. For example, the code set IBM-850 is an alternative for the
US English code set ISO8859-1.
When you have done the conversion, overwrite the cclmsg.txt file with the new
file.
Using an alternative code set on other operating systems
To use an alternate code set, use the iconv routine for the flat file
/bin/cclmsg.txt. For example, to convert /bin/
cclmsg.txt from code set ISO8859-1 to code set ISO-850 enter:
iconv -f ISO8859-1 -t ISO-850 /bin/cclmsg.txt > cclmsg.new
When you have done this conversion, you can overwrite the cclmsg.txt file with
the new file:
mv cclmsg.new /bin/cclmsg.txt
Using X-Window System from a remote system
When using X-Window System from a remote system, for example, to access the
Configuration Tool, you must set up the DISPLAY environment variable to allow
the application to display its windows on that system.
34 CICS Transaction Gateway: UNIX and Linux Administration

On the display system (that is the one that will display the windows), enter the
command:
xhost +appl
where appl is the network name of the system being used to run the application.
On the application system, before you run the application, enter the command:
export DISPLAY=disp:0.0
where disp is the host name or IP address of the system where the windows will
be displayed (followed by a colon and the display id—normally 0.0). The
application windows are then displayed on the disp system.
Chapter 3. Installing the CICS Transaction Gateway 35

36 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 4. Setting up communication with CICS servers
TCP/IP configuration
After you have installed the CICS Transaction Gateway, and set up your CICS
servers for communication, your next step is to set up the communication links
between the CICS Transaction Gateway and your CICS servers.
After you have set up your communications links, continue at Chapter 5,
“Configuration,” on page 49. This tells you how to make the required entries in the
configuration file.
Related information
“Sample configuration documents” on page 211
The TCP/IP stack on your local machine should already be correctly configured.
Contact your system administrator if there are problems.
Verifying the TCP/IP installation
To verify that the CICS Transaction Gateway can communicate with CICS servers,
use the TCP/IP PING command to check the route to the CICS server:
ping [machine address | name]
To start PING, enter a command like the following:
ping 192.113.36.200
where 192.113.36.200 is the IP address of your CICS server. If you are using a
Domain Name Server (DNS), you can specify the symbolic host name rather than the
IP address of the server.
If the statistics message shows a value other than 0% packet loss, it is possible that
TCP/IP is not correctly configured:
v Check for TCP/IP definition errors.
v Check the physical connection to the network.
The PING command differs slightly, depending on your operating system. For
more information, refer to the documentation supplied with your operating
system.
Refer to “TCP/IP settings” on page 72 for information on TCP/IP settings.
On CICS Transaction Server for z/OS
The CICS Transaction Gateway can send ECI requests over TCP/IP to CICS
Transaction Server for z/OS V2.2 and later. To configure this, do the following:
1. Set the SIT parameter TCPIP=YES.
2. Install the following:
v CICS-supplied transient data queue CIEO, in group DFHDCTG
v Transaction CIEP in group DFHIPECI
v Program DFHIEP in group DFHIPECI
© Copyright IBM Corp. 1996, 2006 37

3. Define the TCP/IP address and host name for the z/OS system. By default they
are defined in the PROFILE.TCPIP and TCPIP.DATA data sets.
4. Add a TCP/IP listener to CICS. Use the following CEDA command to define a
TCPIPSERVICE in a group:
CEDA DEF TCPIPSERVICE(service-name) GROUP(group-name)
Ensure that the group in which you define the service is in the startup
GRPLIST, so that the listener starts when CICS is started.
If you specified PJA1TCP as the TCPIPSERVICE, and PJA1GRP as the group,
you see a screen like the following :
OVERTYPE TO MODIFY CICS RELEASE =0620
CEDA DEFine TCpipservice( PJA1TCP )
TCpipservice : PJA1TCP
GROup : PJA1GRP
DEscription ==>
Urm ==>
POrtnumber ==> 08018 1-65535
STatus ==> Open Open | Closed
PRotocol ==> Eci Iiop | Http | Eci
TRansaction ==> CIEP
Backlog ==> 00100 0-32767
TSqprefix ==>
Ipaddress ==> ANY
SOcketclose ==> No No | 0-240000 (HHMMSS)
SECURITY
SSl ==> No Yes | No | Clientaut
Certificate ==>
AUthenticate ==> No | Basic | Certificate | AUTORegister
| AUTOMatic
ATtachsec ==> Verify Local | Verify
SYSID=PJA1 APPLID=SCSCPJA1
DEFINE SUCCESSFUL TIME: 15.30.02 DATE: 02.183
PORTNUMBER
The port on which the TCP/IP service listens.
PROTOCOL
Indicates that the protocol of the service is ECI.
TRANSACTION
The transaction that CICS runs to handle incoming ECI requests. Set it
to CIEP.
BACKLOG
The number of TCP/IP requests that are queued before TCP/IP starts
to request incoming requests.
IPADDRESS
The IP address (in dotted decimal form) on which the TCPIPSERVICE
listens. For configurations with more than one IP stack, specify ANY to
make the TCPIPSERVICE listen on all addresses.
SOCKETCLOSE
Specifies whether CICS should wait before closing the socket after
issuing a receive for incoming data on that socket. NO is recommended
for ECI connections, to ensure that the connection from the Client
daemon always remains open.
ATTACHSEC
Specifies the level of attach-time security required for TCP/IP
connections.
5. Use the following command to install the TCPIPSERVICE definition:
38 CICS Transaction Gateway: UNIX and Linux Administration

Next steps
TCP62 configuration
CEDA INS TCPIPSERVICE(service-name) GROUP(group-name)
1. Use the Configuration Tool to create a server definition; see “The Configuration
Tool interface” on page 50.
2. Configure the server definition (see “Configuring Server settings” on page 70.)
The TCP62 support for CICS Transaction Gateway allows communication with
certain CICS servers over a TCP/IP network. See “Communication with CICS
servers” on page 25 for details of CICS servers that support TCP62.
On CICS Transaction Server for z/OS, you can use autoinstall to define SNA client
connections. The advantage of autoinstall is that it allows you to use the same
client configuration settings for all workstations without having to define multiple
entries in VTAM ®
and CICS. Autoinstall allows the Client Local LU name and CP
name to be created from a template and the IP address of the client machine.
CICS Transaction Gateway TCP62 communication supports only parallel-session
SNA connections, not single-session connections. This has implications for your
CICS VTAM configuration, as explained in “On z/OS” on page 40.
TCP62 links to the CICS Transaction Gateway support data synchronization levels
(sync levels) 0 and 1.
To enable CICS on z/OS to communicate with a CICS Transaction Gateway using
TCP62 requires actions on z/OS, CICS, and the client workstation. This section
outlines the steps you need to take. You also need to make entries in the
configuration file; see Chapter 5, “Configuration,” on page 49.
Table 2 shows the entries that you need to make. The values in the Example
column are taken from the sample configuration documents.
Table 2. Matching definitions for TCP62 on z/OS, CICS, and configuration file.
z/OS CICS Configuration Tool Client workstation Example
IP address - - - 2.12.14.227
DNSUFX - AnyNet domain name
suffix
NETID - Partner LU name. The
Partner LU name is
NETID.APPL.
- hursley.ibm.com
- ABC3XYZ4
APPL Applid Partner LU name - IYCKCTU1
LOGMODE Modename Mode name - LU62PS
- - IP address mask for LU
name template (optional)
- - Fully qualified CP name
or template
- - Local LU name or
template
TCP/IP subnet mask FFFFFE00
- ABC3XYZ4.PQRS1234
- CCLI****
Chapter 4. Setting up communication with CICS servers 39

On z/OS
1. Define the TCP/IP address and host name for the z/OS system in the MVS
TCP/IP PROFILE.TCPIP and TCPIP.DATA data sets.
2. Install a TCP major node, which defines the AnyNet interface between TCP/IP
and VTAM. The important parameters are:
DNSUFX
The domain name suffix, for example hursley.ibm.com. You will enter this
later in the AnyNet domain name suffix field in the Configuration Tool.
TCPIPJOB
The TCP/IP job name refers to the TCP/IP stack that VTAM AnyNet will
use if multiple stacks are in use.
For more information about how to install a major node, see the Guide to SNA
over TCP/IP.
3. To allocate cross-domain resource definitions (CDRSC) dynamically, specify
DYNLU=YES as a startup option for VTAM. If you set this parameter, you do
not need to define multiple static CDRSCs within VTAM. The CDRSC names
are dynamically generated from the CP name and IP address mask for CP
name client configuration settings, along with the IP address of the client
machine.
4. Specify the NETID for VTAM in your VTAM start procedure.
5. Create the VTAM APPL definition. In Table 2 on page 39, this value is
IYCKCTU1. Because TCP62 supports only LU6.2 parallel sessions, specify
PARSESS=YES.
6. Configure a VTAM LOGMODE.
The MPTN (multiprotocol transport networking) function supplied with the
OS/390 ®
or z/OS Communications Server, to provide the SNA over TCP/IP
capability (using AnyNet), is required to complement TCP62 in the client.
On CICS Transaction Server for z/OS
On CICS, do the following:
1. Set the following SIT parameters:
ISC=YES
APPLID=applid
AIEXIT=AIEXIT
In Table 2 on page 39, the APPLID is IYCKCTU1. This is the VTAM APPL that
you defined at step 5. AIEXIT is either DFHZATDY, or the name of an
autoinstall user-replaceable module that you have written.
2. Install these groups:
v DFHISC
v DFHCLNT
3. Define an SNA connection to the client workstation. You can define a static
connection, or autoinstall it. See the CICS Resource Definition Guide for details.
v On the MODENAME option of the SESSIONS definition, specify the same
modename as your VTAM LOGMODE. You will also use this value in the
Mode name field of the configuration file.
v On the MAXIMUM option of the SESSIONS definition, the first number
refers to the Maximum logical SNA sessions field on the Configuration Tool;
see “Maximum logical SNA sessions” on page 78. The default is 8; increase
this if necessary. Specify the second value as 1, that is, that CICS is to have
40 CICS Transaction Gateway: UNIX and Linux Administration

one contention winner. For example, MAXIMUM(8,1) means that the modeset is
to support eight sessions, and that CICS has one contention winner.
See also “Defining SNA connections on CICS Transaction Server for z/OS” on
page 44 for information about defining sessions and connections on CICS
Transaction Server for z/OS.
On the client workstation
If the domain name suffix is SNA.IBM.COM and the fully qualified partner LU name
is NETID.LUA, TCP/IP must be able to resolve LUA.NETID.SNA.IBM.COM to the IP
address of the server. Use one of the following methods to do this:
v Supply the name and IP address to a TCP/IP domain name server
v Add the name and IP addresses in the hosts file (/etc/hosts) on the workstation
Verify that TCP/IP is working correctly. In particular make sure the name formed
from .. can be used to
reach the server. For details on verifying TCP/IP see “Verifying the TCP/IP
installation” on page 37.
Firewall implications
You might experience problems when configuring a TCP62 connection through a
firewall.
For the CICS Transaction Gateway to function correctly your firewall needs to be
configured to permit UDP packets on the TCP62 port, which by default is set to
397; see “TCP62 port” on page 77.
KeepAlive packets
When using CICS Transaction Gateway, with the TCP62 protocol, KeepAlive
packets can be sent to the CICS server to check its availability.
Next steps
SNA configuration
KeepAlive packets are enabled by default.
You can enable or disable the sending of KeepAlive packets using the Remote node
inactivity poll interval (s) setting in the Configuration Tool; see “Remote node
inactivity poll interval (s)” on page 78.
Changing this inactivity poll value alters how frequently the CICS Transaction
Gateway sends KeepAlive packets. A high value reduces network traffic, but the
CICS Transaction Gateway takes longer to detect that a connection has been lost.
With a lower value lost connections are detected quickly, at the cost of more
network traffic.
1. Use the Configuration Tool to create a server definition using the TCP62
protocol; see “The Configuration Tool interface” on page 50.
2. Configure the server definition (see “TCP62 settings” on page 74).
To set up communication over SNA, define the following in your SNA
communications product:
Chapter 4. Setting up communication with CICS servers 41

v The local node characteristics that are common to all SNA users at the
workstation
v A local logical unit (LU) for the CICS Transaction Gateway
v A partner logical unit for each CICS server with which the CICS Transaction
Gateway will communicate
v One or more modes to specify sets of session properties that are used in binding
SNA sessions
v A transaction program (TP) for the CRSR transaction. You need this if:
– The CICS servers support terminal emulation, and
– You require automatic transaction initiation (ATI) against the CICS
Transaction Gateway terminals.
Note: The terms used to describe these definitions vary with the product used to
provide support. The terms used above are the ones used by IBM
Communications Server.
SNA links to the CICS Transaction Gateway support data synchronization levels
(sync levels) 0 and 1.
Configuring for the CICS Transaction Gateway
To run the transport, install and configure a Server, such as IBM Communications
Server. You need to make entries on VTAM, CICS, Communications Server, and the
CICS Transaction Gateway. Table 3 shows the entries that you need to make.
Table 3. Matching definitions for SNA
VTAM CICS
Transaction
Server
IBM
Communications
Server for AIX
NETID — First part of fully
qualified LU name
in Partner LU
PU — Control Point alias
in Node Definition
LU Netname LU Name/LU alias
in independent LU
Type 6.2
XID — Last five digits of
Node identifier in
Node Definition
Token Ring
destination
address
Ethernet
port address
Enterprise
Extender IP
address
— Adjacent node MAC
address in Link
Station
ctg.ini Example
— ABC3XYZ4
— IYAMR021
Local LU name IYAMT210
— 05d316fc
— 400045121088
— MAC address 020070000428
— Communication end
point
APPL APPLID Second part of fully
qualified LU name
in Partner LU
192.113.36.200
— IYCQST34
LogMode Modename Name in Mode Mode name LU62PS
42 CICS Transaction Gateway: UNIX and Linux Administration
— — — Partner LU name IYCQST34

|
Note:
1. The NETID is the VTAM network name. It is defined for your VTAM
network in the VTAM start options.
2. The PU is the name of the AIX physical unit (PU). It is named in the
VTAM switched major node.
3. The LU is the independent LU6.2 used by the CICS Transaction Gateway.
It must also be defined to VTAM in a switched Major Node.
4. The XID (or node ID) is configured in the VTAM switched major node
using IDBLK and IDNUM. It is used in the XID exchange to activate the
link station.
5. For IBM Communications Server, Token Ring, Ethernet and Enterprise
Extender are all valid communication link station types. Choose one or
more as required. For more details about link station configuration refer
to the Communications Server Task Guides.
6. The APPL is is the CICS APPLID and also the VTAM APPL. It is defined
in the VTAM application major node used by the CICS region.
7. The LogMode is the mode group used to control LU6.2 session
properties. It must be defined in a VTAM logon mode table, which must
be named on the VTAM APPL definition.
8. The Host system control point name is the CP for the PU of the VTAM
front end processor.
More information on connecting the CICS Transaction Gateway to CICS
Transaction Server for z/OS is in CICS Transaction Gateway V5 - The WebSphere
Connector for CICS, SG24-6133.
Configuring Communications Server for Linux
Communications Server for Linux requires various environment variables to be
defined. Refer to the README file supplied with the server and ensure that all
variables are correctly set, including LD_PRELOAD. Do not set the LD_PRELOAD
variable globally.
To ensure that messages can be written to error logs, the user who starts the Client
daemon process must be a member of the ’sna’ group. Read the man page for
ld.so for information about security issues associated with LD variables.
Configuring SNA Communications product
To enable ATI against Communications Server client terminals, define the
transaction program CRSR on the Server. Follow the instructions in the
Administration Guide. To define the transaction program using X-Window System:
1. Start the administration application, xsnaadmin.
2. Select Services—>APPC—> Transaction Programs.
3. Select TP invocation.
4. Click Add or, on Linux, New.
5. Enter CRSR as the Application TP.
6. Indicate Parameters are for invocation on any LU Queue incoming allocates
and enter the path to the executable as: /usr/bin/cclclnt
7. Set Arguments to CRSR
8. Set Userid to root and Group to system.
Chapter 4. Setting up communication with CICS servers 43

|
|
|
|
9. Close the TP definition window.
10. In the Local LU advanced parameters, ensure that the Attach routing
computer host name is entered.
11. On the remote API client, ensure that invoked_tps = YES is set in the
sna_clnt.net configuration file.
Defining SNA connections on CICS Transaction Server for
z/OS
To define SNA connections from CICS do the following:
1. Specify the SIT parameter ISC=YES
2. Install CSD groups DFHCLNT and DFHISC
3. Create and install CICS connection and sessions definitions, as described later
in this information
CICS connection definition
This defines the location of the remote system, and the parameters of the
connection to it. Use CEDA to set the following:
ACcessmsmethod
Set this to Vtam.
PRotocol
Set this to Appc.
Singlesess
Set this to No.
AUtoconnect
This specifies whether CICS is to bind sessions (drive CNOS) when the
connection is installed. Set this to Yes.
ATtachsec
This defines the settings for SNA LU6.2 conversation level security. Set it to
one of the following:
v Verify — to flow a user ID and password from the CICS Transaction
Gateway.
v LOCAL — if you do not want to flow a user ID and password.
Netname
Set this to the LU name of the partner LU6.2
Note: If you change and reinstall the CICS connection definition, you must stop
and restart the connection.
CICS sessions definition
For each CICS connection definition, define one or more sessions definitions to
define the SNA mode groups to be used within that connection.
Connection
Set this to the name of the associated connection definition.
MOdename
Specifies the mode group as defined in a VTAM LOGMODE. The modename
must be unique among the sessions definitions that relate to one connection
definition.
Protocol
Set this to APPC.
44 CICS Transaction Gateway: UNIX and Linux Administration

Data conversion
MAximum
Specifies the maximum number of sessions that are to be supported. The first
value is the maximum number of sessions that can be supported. The second
value specifies the number of contention-winner sessions (CICS-owned
sessions). These values are negotiated during change number of sessions
(CNOS) flows, when the sessions are actually bound; the negotiated values
depend on the settings specified in the partner SNA node.
Set the first value to be at least as big as the MAXREQUESTS parameter in the
ctg.ini file, to prevent this becoming a bottleneck to throughput. Set the second
value to 001, to ensure that START requests are shipped serially from the
server to the client.
Autoconnect
This determines whether the sessions for this mode group will be bound when
the connection is installed. Set it to one of the following:
v Yes — to bind only contention-winner sessions
v All — to bind all sessions
CICS connection autoinstall
Autoinstall of connections is particularly useful when dealing with many similar
connections, or when you are unsure of the LU names (netnames) to be used. This
will be the case if you are using dynamic LUs with TCP62 connections from the
Client daemon. To configure autoinstall of connection definitions, do the following:
1. Update the default autoinstall program from DFHZATDX to DFHZATDY, by
specifying the SIT parameter AIEXIT=DFHZATDY. Alternatively, write your
own autoinstall user-replaceable module based on the samples provided.
2. Configure model definitions. The supplied DFHZATDY autoinstall program
uses the template CBPS. This is supplied in DFHAI62 group; copy it to your
own group, and modify it accordingly. The parameters in the connection
definition template are the same as for a static definition (see “CICS connection
definition” on page 44), except that the netname is not needed.
The parameters for the sessions definition are the same as those listed in “CICS
sessions definition” on page 44, except that the Connection parameter should
refer to the CBPS connection definition.
If you use the supplied connection autoinstall program (DFHZATDY), the
connection name generated is based on the last four characters of the Netname. To
change this, create your own user-replaceable module from the sample provided in
CICSTS22.CICS.SDFHSAMP.
The ECI and EPI allow non-CICS applications running in a client system to access
CICS facilities and data managed by a CICS server system. Character data might
need to be converted as it is passed between client and server; for example data is
encoded in ASCII on a CICS Transaction Gateway system and in EBCDIC on a
CICS mainframe server system. Data conversion is performed by the server
system. For more information on this see Appendix A, “Data conversion when
using the Client daemon and a CICS server,” on page 193.
Chapter 4. Setting up communication with CICS servers 45

Configuring message queues
In UNIX and Linux systems, the Client daemon communicates internally using
message queues. In systems other than AIX, the default configuration settings for
these queues are too small to allow for large client data flows (such as 3270 maps
or user COMMAREAs). Some symptoms of this problem are:
v An ECI program gives return code -3 (ECI_ERR_NO_CICS)
v A cicsterm locks when a large map is sent to it
v A large number of concurrent ECI requests significantly degrades performance
It is recommend that you change the configuration settings of the message queues
to allow for large client data flows.
The way that you do this depends on your operating system:
v “Message queues on HP-UX”
v “Message queues on Linux”
v “Message queues on Solaris” on page 47
Message queues on HP-UX
The following settings are recommended:
msgssz 32 Message Segment Size
msgmnb 65535 Max Number of Bytes on Message Queue
msgmax 65535 Message Max Size (bytes)
msgseg 16384 Number of Segments Available for Messages
Set these values by using the SAM utility:
1. Type sam at the command prompt.
2. Select Kernel Configuration —> Configurable Parameters.
This displays a list of kernel parameters that you can change.
3. Select a parameter, either by clicking on it with the mouse or by moving the
cursor to it and pressing the enter key.
4. Select Actions —> Modify configurable parameter.
5. Enter the new value for the parameter in the Formula/Value field, and then
select OK.
If the value you entered is not valid, SAM displays a window explaining the
error.
6. When you have made all of the required changes, select Actions —> Process
New Kernel.
SAM displays a window asking for confirmation; select Yes.
SAM then compiles the kernel and displays a window asking if you want to
replace the old kernel before restarting the system. You must restart the system for
the changes to take effect.
Message queues on Linux
You are recommended to place the following settings in file /etc/sysctl.conf:
kernel.msgmni=128 #Max # of msg queue identifiers
kernel.msgmnb=163840 #Size of message queue
kernel.msgmax=40960 #Max size of a message
v On Red Hat, the new settings are used after you restart the computer.
v On SuSE, issue the command chkconfig boot.sysctl on, and then reboot.
46 CICS Transaction Gateway: UNIX and Linux Administration

v To check that the new settings have been applied, issue the command sysctl -a.
The MSGMNI variable determines the maximum number of message queue
identifiers system wide. This is typically set to 128 which is sufficient for the
normal number of concurrent requests expected to be processed.
Message queues on Solaris
The following settings are recommended:
set msgsys:msginfo_msgmax = 65535 Maximum size of System V message.
set msgsys:msginfo_msgmnb = 65535 Maximum number of bytes that can be on any
one message queue.
set msgsys:msginfo_msgssz = 32 Specifies size of chunks system uses to
manage space for message buffers.
Obsolete since the Solaris 8 release.
set msgsys:msginfo_msgseg = 16384 Number of msginfo_msgssz segments the system
uses as a pool for available message memory.
Total memory available for messages is
msginfo_msgseg * msginfo_msgssz.
Obsolete since the Solaris 8 release.
set semsys:seminfo_semmni = 4096 Maximum number of semaphore identifiers.
set msgsys:msginfo_msgtql = 10000 The maximum number of queue entries that
can be in the system at the same time.
A low value can adversely affect
system performance, or cause the
client to freeze. IBM recommends that
you set this value to the maximum (10000),
or at least double the maximum number of
concurrent requests. Stress load your
system, and then use the ipcs -qa command
to determine the setting.
Set these values by changing the entries in the /etc/system file. See Solaris system
notes for information on changing this file.
Chapter 4. Setting up communication with CICS servers 47

48 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 5. Configuration
This information describes how to configure your CICS Transaction Gateway.
Related concepts
Chapter 15, “Statistics introduction,” on page 185
This information introduces the statistics that are available from the CICS
Transaction Gateway.
Related information
“Sample configuration documents” on page 211
“Redbooks” on page 211
Chapter 4, “Setting up communication with CICS servers,” on page 37
Before you start to configure your system
This section covers some of the things you need to do before running the
Configuration Tool. In particular, make sure that communication links with your
CICS servers are correctly set up; see Chapter 4, “Setting up communication with
CICS servers,” on page 37.
Gather information
Have the following information available:
v The protocol you will use to connect to the CICS server (TCP/IP, TCP62, SNA)
v The host name or IP address of the server
v The port number at the server to which the Client daemon should connect
v The protocols that you will use with the Gateway (TCP, SSL)
See Table 2 on page 39, and Table 3 on page 42, for information on matching
definitions for TCP62 and SNA.
Configure your programming environment
This section applies if you are running the CICS Transaction Gateway remotely.
The Java Virtual Machine (JVM) uses the CLASSPATH environment variable to
find classes, and zip or jar archives containing classes. To allow the JVM to access
class files, you must specify the full path of directories containing class files or
archives.
To compile and run Java applications for use with the CICS Transaction Gateway,
add the full path of the following to the CLASSPATH environment variable:
v ctgclient.jar
v ctgserver.jar (if you are using a local Gateway)
These archives are in the /classes subdirectory.
Recommended Java options for the Solaris JVM
You are recommended to use the -XX:+UseLWPSynchronization Java option with
Java Client applications.
Also ensure that /usr/lib/lwp appears before /usr/lib in the LD_LIBRARY_PATH
variable.
© Copyright IBM Corp. 1996, 2006 49

|
|
|
|
|
|
|
|
|
|
|
Using the Configuration Tool
If you do not set these options, calls to the JavaGateway.open() method might hang
when either the TCP/IP or the SSL protocol is used. See your Solaris
documentation for more details.
Use the Configuration Tool to configure the CICS Transaction Gateway.
To use the Configuration Tool remotely, export the display using the commands
described in “Using X-Window System from a remote system” on page 34. To start
the Configuration Tool, enter the ctgcfg command.
Configuration file
Configuration details are stored by default in the ctg.ini file in the
/bin subdirectory. You are recommended to use the Configuration
Tool to update this file.
You can specify a different location for the configuration file, and optionally
change its name, by setting the CICSCLI environment variable. If this variable is
set, at startup the Configuration Tool loads the file referenced by CICSCLI. If the
Configuration Tool fails to find the configuration file, it creates a file that includes
a partial definition for a new server named A_Server. This file must be edited and
saved before use. The tool does not automatically create a directory if the directory
referenced by CICSCLI does not exist.
The CICS Transaction Gateway log indicates the name and location of the INI file.
The CICS Transaction Gateway will not run if a configuration file is not found.
Running the Configuration Tool for a different operating
system
Proceed as follows:
1. Install the CICS Transaction Gateway on the workstation on which you want to
run the Configuration Tool.
2. To edit an existing configuration, copy ctg.ini to the /bin
subdirectory on the workstation, using FTP in ASCII mode.
3. Issue the following command to display help about the Configuration Tool:
ctgcfg -?
4. Issue the following command:
ctgcfg -PLAT OSCODE
where OSCODE represents the operating system that the Configuration Tool
should emulate, and is one of the values returned by the command that you
issued at step 3.
5. Make the required entries and click Save. This creates or updates the ctg.ini
file.
6. Use FTP in ASCII mode to transfer the file to your system.
The Configuration Tool interface
The screen has these input areas (described separately below):
1. Menu bar
2. Toolbar
50 CICS Transaction Gateway: UNIX and Linux Administration

Figure 9. The Configuration Tool
3. Navigation panel
4. Settings panel
A fifth area, the status bar, shows which configuration file and operating system
you are using. The status bar is display only.
Note: Screen captures later in this chapter show the Configuration Tool running
for the Windows operating system. On your platform, the Configuration
Tool might look slightly different.
Navigation panel
The navigation panel (see Figure 9) allows you to navigate through all of the
settings in your configuration. The tree has the following root nodes:
Gateway daemon
Contains a subnode for each protocol that the CICS Transaction Gateway
can use.
Client daemon
Contains a subnode for each of your server definitions.
Chapter 5. Configuration 51

|
|
|
|
|
|
|
Menu bar
The menu bar contains the File, Edit, Tools, Settings, and Help menus.
The File menu has the following options:
New Creates a new configuration.
Open Opens an existing configuration.
Save Saves the current configuration. By default, the file name is ctg.ini, and
saved to the /bin subdirectory.
Save As
Allows you to override the default path and name of the configuration file.
Exit Exits the Configuration Tool. If you have made any alterations you are
asked whether you want to save the configuration.
The Edit menu has Cut, Copy and Paste options, which perform the standard text
functions.
The Options menu has the following options:
Trace Settings
Displays the Trace Settings dialog.
New Server
Defines a new server named A_Server, that uses the TCP protocol.
Delete Server
Deletes a server node from the navigation panel.
The Settings menu has these options:
Color Changes the background color on panels and fields. If you change the
color, all fields (except check boxes and radio buttons) take on the same
background color as the main panel.
Font Changes the typeface, size, style and color of text. You can also change the
color of warning text.
Save on exit
If this menu option is selected, your choices are stored in CTGCFG.INI, for
use in future sessions. A copy of CTGCFG.INI is created for each user in
the user’s home directory (~/.ctg).
Note:
1. The file is not deleted if the CICS Transaction Gateway is
uninstalled. It remains on the system unless manually deleted,
and will be reused if the product is reinstalled.
2. To restore the default settings, close the Configuration Tool,
delete file CTGCFG.INI, and then restart the Configuration Tool.
3. When you close the Configuration Tool, a message is displayed if
file CTGCFG.INI cannot be written—even if you have deselected
the Save on exit menu option. Click OK to clear the message
and close the Configuration Tool.
The Help menu has the following options:
52 CICS Transaction Gateway: UNIX and Linux Administration

Context Help
Displays online help information according to the current screen context,
for example, for a particular configuration setting.
Contents
Displays the contents list for online help.
Keys Help
Displays information on keyboard alternatives, and other information to
help users with a disability to use the software. See also “Accessibility
features for CICS Transaction Gateway” on page 215.
Index Displays a subject index for online help.
About Displays the version number and other information about the
Configuration Tool.
Toolbar
The toolbar provides some of the functionality available from the menu bar in a set
of icons. These icons have hover help, so that when you place the cursor over them,
a text box describing the option appears.
Settings panels
When you select nodes in the navigation panel, the relevant settings panel is
displayed. The settings in these panels correspond to parameters in the ctg.ini file.
On each settings panel there is an Undo Changes button that allows you to undo
changes you have made.
Configuring Gateway daemon settings
To display the Gateway daemon settings panel, select the Gateway node in the tree
structure. The settings map to the parameters in the Gateway section of the ctg.ini
file.
Using the Configuration Tool, you can provide preset values for any parameter
that can be specified using a Gateway command line option.
If a parameter that has been defined using the Configuration Tool is specified via
the associated command line option when the Gateway is started, the command
line setting takes precedence.
Gateway daemon settings
Select the Gateway daemon node to work with the general settings for the
Gateway daemon. The panel has these tabs:
Resources
Logging
See Figure 9 on page 51 for the screen layout.
Initial number of Connection Manager threads: Enter a number in the range 1
through 1 000 000, to specify the initial number of ConnectionManager threads.
Set this to the normal number of JavaGateway objects opened by all connected
Java clients. The default is 1. You might need to set this to less than the supported
maximum value due to constraints on memory or other system resources. If you
enter a value outside the permitted range, the Configuration Tool warns you. If the
value entered is too low, it substitutes the minimum. If the value entered is too
high, it substitutes the maximum. If a non-numeric value is present in the
configuration file, it substitutes the minimum value.
Chapter 5. Configuration 53

You can override this setting with the ctgstart -initconnect=number command.
For details of the corresponding entry in the configuration file, see initconnect
(“ctg.ini: GATEWAY section” on page 203).
Maximum number of Connection Manager threads: Enter a number in the range
1 through 1 000 000, to specify the maximum number of ConnectionManager
threads. The default is 100. You might need to set this to less than the supported
maximum value due to constraints on memory or other system resources. If you
enter a value outside the permitted range, the Configuration Tool warns you. If the
value entered is too low, it substitutes the minimum. If the value entered is too
high, it substitutes the maximum. If a non-numeric value is present in the
configuration file, it substitutes the minimum value.
This limits the maximum number of JavaGateway objects opened by all connected
Java Client applications. Set this to the maximum number of JavaGateway objects
that could be open at any one time from all the remotely-connected Java Client
applications.
If you select the Unrestricted check box, no limits are applied to the number of
ConnectionManager threads.
You can override this setting with the ctgstart -maxconnect=number command.
For information on threading limits, see “The CICS Transaction Gateway threading
model” on page 113.
For details of the corresponding entry in the configuration file, see maxconnect
(“ctg.ini: GATEWAY section” on page 203).
Initial number of Worker threads: Enter a number in the range 1 through
1 000 000, to specify the initial number of worker threads. The default is 1. You
might need to set this to less than the supported maximum value due to
constraints on memory or other system resources. If you enter a value outside the
permitted range, the Configuration Tool warns you. If the value entered is too low,
it substitutes the minimum. If the value entered is too high, it substitutes the
maximum. If a non-numeric value is present in the configuration file, it substitutes
the minimum value.
Set this to the normal number of concurrent requests expected to be processed
concurrently by the Gateway daemon.
You can override this setting with the ctgstart -initworker=number command.
For details of the corresponding entry in the configuration file, see initworker
(“ctg.ini: GATEWAY section” on page 203).
Maximum number of Worker threads: Enter a number in the range 1 through
1 000 000, to specify the maximum number of worker threads. The default is 100.
You might need to set this to less than the supported maximum value due to
constraints on memory or other system resources. If you enter a value outside the
permitted range, the Configuration Tool warns you. If the value entered is too low,
it substitutes the minimum. If the value entered is too high, it substitutes the
maximum. If a non-numeric value is present in the configuration file, it substitutes
the minimum value.
54 CICS Transaction Gateway: UNIX and Linux Administration

This limits the maximum number of parallel ECI, ESI and EPI requests that the
CICS Transaction Gateway can process.
Set it to be less than or equal to maxconnect.
If you select the Unrestricted check box, no limits are applied to the number of
worker threads.
You can override this setting with the ctgstart -maxworker=number command.
For information on threading limits, see “The CICS Transaction Gateway threading
model” on page 113.
For details of the corresponding entry in the configuration file, see maxworker
(“ctg.ini: GATEWAY section” on page 203).
Enable reading input from console: Select this check box to enable the reading of
input from the console. The field is enabled by default.
See also the -quiet command line option (“Starting the Gateway daemon with
preset options” on page 123).
For details of the corresponding entry in the configuration file, see noinput
(“ctg.ini: GATEWAY section” on page 203).
Let Java Clients obtain generic ECI replies: Select this check box if you want
Java Client applications to be able to obtain generic ECI replies from the CICS
Transaction Gateway.
Generic replies are those obtained using the Call_Type: ECI_GET_REPLY or
ECI_GET_REPLY_WAIT. Specific replies are those obtained using the Call_Type:
ECI_GET_SPECIFIC_REPLY or ECI_GET_SPECIFIC_REPLY_WAIT. This setting
does not apply to local Gateways. The default is that generic replies are not
enabled; enabling generic replies is deprecated.
For details of the corresponding entry in the configuration file, see ecigenericreplies
(“ctg.ini: GATEWAY section” on page 203).
Validate Units of Work: Select this check box if you want the CICS Transaction
Gateway to validate logical units of work (LUWs). This ensures that a LUW ID can
be used only on the JavaGateway connection to which it was allocated. If you clear
this check box, you disable validation:
v LUWs can be accessed by any connection to the same remote Gateway.
v The CICS Transaction Gateway cannot clean up used LUWs when a connection
is closed or breaks.
The default is that LUW validation is enabled; disabling validation is deprecated.
For details of the corresponding entry in the configuration file, see uowvalidation
(“ctg.ini: GATEWAY section” on page 203).
Validate message qualifiers: Select this check box if you want the CICS
Transaction Gateway to validate message qualifiers. This ensures that a message
qualifier ID can be used only on the JavaGateway connection to which it was
Chapter 5. Configuration 55

allocated. A message qualifier that has been assigned on an asynchronous call
cannot be used by any connection using the same remote Gateway until the reply
has been received.
If you clear this check box, you disable validation:
v ECI asynchronous calls tagged with a message qualifier on one connection can
have a call of the GET_SPECIFIC_REPLY type made from another connection to
the same remote gateway.
v A message qualifier can be used on an asynchronous call even if a reply with
the same message qualifier is still outstanding in the remote Gateway.
v The CICS Transaction Gateway cannot clean up used message qualifiers when a
connection is closed or breaks. In some circumstances logical units of work
(LUWs) will also not be cleaned up: because the Gateway cannot clean up the
message qualifier, it cannot determine if the LUW is still active.
The default is that message qualifier validation is enabled; disabling validation is
deprecated.
For details of the corresponding entry in the configuration file, see
msgqualvalidation (“ctg.ini: GATEWAY section” on page 203).
Timeout for in-progress requests to complete (ms): Enter a number in the range
0 through 1 000 000, to specify the value in milliseconds. The default timeout is
10 000 milliseconds. If you enter a value outside the permitted range, the
Configuration Tool warns you. If the value entered is too low, it substitutes the
minimum. If the value entered is too high, it substitutes the maximum. If a
non-numeric value is present in the configuration file, it substitutes the minimum
value.
When a Java Client application disconnects from the CICS Transaction Gateway,
the Gateway might still be processing requests on behalf of that program.
1. The ConnectionManager that was managing requests on behalf of the Java
Client application waits for outstanding requests to complete for up to the
timeout period. If this field is set to zero, the Connection Manager moves
immediately to step 2.
2. After the timeout has expired, the ConnectionManager closes the protocol
handler and returns any worker threads without in-progress requests to the
pool.
3. When all in-progress requests have completed, the ConnectionManager returns
itself to the pool for reuse.
For details of the corresponding entry in the configuration file, see closetimeout
(“ctg.ini: GATEWAY section” on page 203).
Worker thread available timeout (ms): Enter a number in the range 0 through
1 000 000, to specify the value in milliseconds. If you enter a value outside the
permitted range, the Configuration Tool warns you. If the value entered is too low,
it substitutes the minimum. If the value entered is too high, it substitutes the
maximum. If a non-numeric value is present in the configuration file, it substitutes
the minimum value.
When a ConnectionManager accepts a request, it must allocate a worker thread to
execute that request. If a worker thread does not become available within the
56 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
timeout period, an error message is sent rejecting that request and the request is
not executed. The default timeout is set to 10 000 milliseconds, but you can enter a
value to override that default.
If you set this value to zero, the request is rejected unless a worker thread is
immediately available.
For details of the corresponding entry in the configuration file, see workertimeout
(“ctg.ini: GATEWAY section” on page 203.)
Port for local administration: Enter a value in the range 1 through 65 535, to
specify the port number on which to listen for administration requests. The default
is 2810. If you enter a value outside the permitted range, the Configuration Tool
warns you. If the value entered is too low, it substitutes the minimum. If the value
entered is too high, it substitutes the maximum. If a non-numeric value is present
in the configuration file, it substitutes the minimum value.
You can override this setting with the ctgstart -adminport=number command.
For details of the corresponding entry in the configuration file, see adminport
(“ctg.ini: GATEWAY section” on page 203).
Statistics API port:
The Statistics API port allows the Gateway daemon to handle incoming requests
for the Statistics API.
Enter a value in the range 1 through 65 535, to specify the port number on which
to listen for Statistics API requests. The default is 2980. If you enter a value outside
the permitted range, the Configuration Tool warns you. If the value entered is too
low, it substitutes the minimum. If the value entered is too high, it substitutes the
maximum. If a non-numeric value is present in the configuration file, it substitutes
the minimum value.
The port is not available by default. If you clear the Disabled check box, the
Statistics API port field is available and the Gateway daemon listens for incoming
requests on the specified port.
You can override this setting with the ctgstart -statsport=number command.
For details of the corresponding entry in the configuration file, see statsport
(“ctg.ini: GATEWAY section” on page 203).
If the Configuration Tool loads a configuration file without a statsport parameter,
the Disabled check box is selected. An incorrect statsport parameter in ctg.ini sets
the port to 1.
Display TCP/IP hostnames: Select this check box to enable the display of TCP/IP
host names in messages.
This option allows you to choose how TCP/IP addresses are displayed in
messages. By default, CICS Transaction Gateway displays TCP/IP addresses in
messages in numeric form. If you enable this option, CICS Transaction Gateway
uses the Domain Name System (DNS) to convert numeric TCP/IP addresses to
symbolic TCP/IP host names in messages. This makes the messages easier to read.
Chapter 5. Configuration 57

Note: Selecting this option might cause severe performance reduction on some
systems.
For details of the corresponding entry in the configuration file, see nonames
(“ctg.ini: GATEWAY section” on page 203).
Log Java Client connections and disconnections: Select this check box if you
want CICS Transaction Gateway to write a message to the log each time that a Java
Client application connects to, or disconnects from, the Gateway daemon. The
default is for these messages not to be written.
For details of the corresponding entry in the configuration file, see
connectionlogging (“ctg.ini: GATEWAY section” on page 203).
Error and warning log destination: Select the destination for error and warning
messages output by the Gateway daemon. The Console option sends output to
stderr.
For details of the corresponding entry in the configuration file, see log@error.dest
(“ctg.ini: GATEWAY section” on page 203).
Error log file name: Enter the name of the log file to be used for error and
warning messages. The file name cannot contain the % (percent) character. Use
either a forward slash (/) character, or double back slash (\\) characters, as a
separator in the path name on all platforms. For example:
/logs/mylogs.txt
\\logs\\mylogs.txt
For details of the corresponding entry in the configuration file, see
log@error.parameters (“ctg.ini: GATEWAY section” on page 203).
Error log maximum size (KB): Enter a value in the range 0 through 2 097 151, to
specify the maximum size in kilobytes of the log file. A value of 0 means that no
limit is placed on the file size. The default value is 0. If you enter a value outside
the permitted range, the Configuration Tool warns you. If the value entered is too
low, it substitutes the minimum. If the value entered is too high, it substitutes the
maximum. If a non-numeric value is present in the configuration file, it substitutes
the minimum value.
For details of the corresponding entry in the configuration file, see
log@error.parameters (“ctg.ini: GATEWAY section” on page 203).
Maximum number of archived error log files: Enter a value in the range 1
through 9999, to specify the maximum number of archived log files that are
maintained. The default value is 1. If you enter a value outside the permitted
range, the Configuration Tool warns you. If the value entered is too low, it
substitutes the minimum. If the value entered is too high, it substitutes the
maximum. If a non-numeric value is present in the configuration file, it substitutes
the minimum value. Any entry in this field is ignored if the “Error log maximum
size (KB)” field has a value of 0. A value greater than 1 means that the log files
will be rotated when the currently active log file reaches or exceeds the filesize
limit. The file name of the currently active log file is suffixed by ’.0’ and the
rotation process closes this file. The log file with the file name that has a suffix of
’.maxfiles-1’, is then erased, if it exists and all the other log files are renamed by
adding one to the suffix. Finally, a new log file with suffix ’.0’ is opened as the
58 CICS Transaction Gateway: UNIX and Linux Administration

new active log file. For example, if you set “Error log file name” on page 58 to
ctg.log, and the Maximum number of archived information log files field to 4, at
most the following files will be created:
ctg.log.3 This is the oldest log file.
ctg.log.2
ctg.log.1
ctg.log.0 This is the log file currently being written to.
When ctg.log.0 becomes full it is closed. ctg.log.3 is erased. ctg.log.0 becomes
ctg.log.1, ctg.log.1 becomes ctg.log.2, ctg.log.2 becomes ctg.log.3, and a new log file
ctg.log.0 is opened as the currently active log file. In other words the smaller the
file name suffix the newer the log file.
For details of the corresponding entry in the configuration file, see
log@error.parameters (“ctg.ini: GATEWAY section” on page 203).
Use the same settings for error and information logs: Select this check box if you
want the information log to be output to the same destination as the error and
warning log.
Information log destination: Select the destination for information messages
output by the Gateway daemon. The Console option sends output to stdout.
For details of the corresponding entry in the configuration file, see log@info.dest
(“ctg.ini: GATEWAY section” on page 203).
Information log file name: Enter the name of the log file to be used for
information messages. The file name cannot contain the % (percent) character. Use
either a forward slash (/) character, or double back slash (\\) characters, as a
separator in the path name on all platforms. For example:
/logs/mylogs.txt
\\logs\\mylogs.txt
For details of the corresponding entry in the configuration file, see
log@info.parameters (“ctg.ini: GATEWAY section” on page 203).
Information log maximum size (KB): Enter a value in the range 0 through
2 097 151, to specify the maximum size in kilobytes of the log file. A value of 0
means that no limit is placed on the file size. The default value is 0. If you enter a
value outside the permitted range, the Configuration Tool warns you. If the value
entered is too low, it substitutes the minimum. If the value entered is too high, it
substitutes the maximum. If a non-numeric value is present in the configuration
file, it substitutes the minimum value.
For details of the corresponding entry in the configuration file, see
log@info.parameters (“ctg.ini: GATEWAY section” on page 203).
Maximum number of archived information log files: Enter a value in the range
1 through 9999, to specify the maximum number of archived log files that are
maintained. The default value is 1. If you enter a value outside the permitted
range, the Configuration Tool warns you. If the value entered is too low, it
substitutes the minimum. If the value entered is too high, it substitutes the
maximum. If a non-numeric value is present in the configuration file, it substitutes
the minimum value. Any entry in this field is ignored if the “Information log
maximum size (KB)” field has a value of 0. A value greater than 1 results in the file
name of the log file being suffixed by sequence numbers until the number of
archived files specified in maxfiles have been created. For example, if you set
Chapter 5. Configuration 59

Figure 10. TCP settings
“Information log file name” on page 59 to ctg.log, and the Maximum number of
archived information log files field to 4, at most the following files will be created:
ctg.log.3 This is the oldest log file.
ctg.log.2
ctg.log.1
ctg.log.0 This is the log file currently being written to.
In other words the smaller the filename suffix the newer the log file.
For details of the corresponding entry in the configuration file, see
log@info.parameters (“ctg.ini: GATEWAY section” on page 203).
TCP protocol settings
Select the TCP subnode to display the settings for TCP:
Enable protocol handler: Select this check box to configure the CICS Transaction
Gateway for use with this protocol.
Bind Address: The protocol handler can be bound to an individual IP address,
which is entered here. Enter an IP address or a host name. If you enter a host
name, it is resolved on startup.
To bind the protocol to all addresses, leave the field blank.
60 CICS Transaction Gateway: UNIX and Linux Administration

|
|
The default behavior is to bind all addresses.
The IP address can be in IPv6 format, for example
3ffe:307:8:0:260:97ff:fe40:efab.
Port: Enter a number in the range 1 through 65 535 to specify the TCP/IP port
number. If you enter a value outside the permitted range, the Configuration Tool
warns you. If the value entered is too low, it substitutes the minimum. If the value
entered is too high, it substitutes the maximum. If a non-numeric value is present
in the configuration file, it substitutes the minimum value.
The default port for TCP/IP is 2006.
You can override this setting with the ctgstart -port=number command.
For details of the corresponding entry in the configuration file, see port (“ctg.ini:
GATEWAY section” on page 203).
Connection timeout (ms): Enter a number in the range 0 through 65 536, to
specify the value in milliseconds. If you enter a value outside the permitted range,
the Configuration Tool warns you. If the value entered is too low, it substitutes the
minimum. If the value entered is too high, it substitutes the maximum. If a
non-numeric value is present in the configuration file, it substitutes the minimum
value.
When a new connection has been accepted, this value specifies how long the
protocol handler waits for a ConnectionManager thread to become available. If a
ConnectionManager thread does not become available within this time, the
connection is refused. If this value is set to zero, a connection is refused if a
ConnectionManager is not immediately available.
For details of the corresponding entry in the configuration file, see connecttimeout
(“ctg.ini: GATEWAY section” on page 203).
Idle timeout (ms): Enter a value in milliseconds, between 0 and 9 999 999. If you
enter a value outside the permitted range, the Configuration Tool warns you. If the
value entered is too low, it substitutes the minimum. If the value entered is too
high, it substitutes the maximum. If a non-numeric value is present in the
configuration file, it substitutes the minimum value.
This setting specifies how long a connection is allowed to remain dormant. The
idle timeout period is counted from when a request was last flowed down the
connection. When the idle timeout has expired, the Java Client application is
disconnected, although if work is still in progress on behalf of the connection, it
might be left connected, depending on the setting of the “Drop working
connections” on page 62 field. If the Idle timeout (ms) field is not set, or is set to
zero, idle connections will not be disconnected.
Cleanup processing will only result after a timeout if the server has support for
this function installed.
For details of the corresponding entry in the configuration file, see idletimeout
(“ctg.ini: GATEWAY section” on page 203).
Ping time frequency (ms): Enter a number in the range 0 through 65 536, to
specify the value in milliseconds. If you enter a value outside the permitted range,
Chapter 5. Configuration 61

the Configuration Tool warns you. If the value entered is too low, it substitutes the
minimum. If the value entered is too high, it substitutes the maximum. If a
non-numeric value is present in the configuration file, it substitutes the minimum
value.
This value specifies how often a ping message is sent by the Gateway to an
attached client to check that client is still active. If a reply has not been received by
the time the next ping message is due to be sent, the connection is disconnected.
Again, if work is still in progress on behalf of the connection it might (depending
on the drop working connections value setting) be left connected. If this value is
not set, or is set to zero, ping messages are not sent.
For details of the corresponding entry in the configuration file, see pingfrequency
(“ctg.ini: GATEWAY section” on page 203).
Drop working connections: Select this check box to specify that a connection can
be disconnected, due to an idle timeout or a PING/PONG failure even if work is
still in progress on behalf of this connection.
For details of the corresponding entry in the configuration file, see “ctg.ini:
GATEWAY section” on page 203 (dropworking).
SO_LINGER setting: Enter a number in the range 0 through 65 536, to specify
the SO_LINGER setting for any socket used by this handler. The SO_LINGER
setting is a delay value in seconds for closing a socket. If this value is not entered,
or is set to zero, SO_LINGER is disabled for any sockets used by this protocol
handler. If you enter a value outside the permitted range, the Configuration Tool
warns you. If the value entered is too low, it substitutes the minimum. If the value
entered is too high, it substitutes the maximum. If a non-numeric value is present
in the configuration file, it substitutes the minimum value.
If SO_LINGER is enabled, and data transmission has not finished, a call to close
the socket blocks the calling program until the data is transmitted or until the
connection times out. If SO_LINGER is disabled, a call to close the socket returns
without blocking the caller and TCP/IP still tries to send the data. Normally this
transfer is successful, but it cannot be guaranteed, because TCP/IP repeats the
Send request for only a specified period of time.
For details of the corresponding entry in the configuration file, see solinger
(“ctg.ini: GATEWAY section” on page 203).
Require Java Clients to use security classes: Select this check box if you want
your Gateway to accept only connections that use security classes.
When a Java Client application connects to the Gateway, it can specify a pair of
security classes for use on the connection. However, by default a Gateway also
accepts connections from programs that do not specify this pair of security classes.
For more information on CICS Transaction Gateway security exits, see “Security
exits” on page 10.
For details of the corresponding entry in the configuration file, see requiresecurity
(“ctg.ini: GATEWAY section” on page 203).
SSL protocol settings
62 CICS Transaction Gateway: UNIX and Linux Administration

Figure 11. SSL settings
Select the SSL subnode to display the settings for SSL. These settings can be added
manually to the configuration file as explained in “SSL protocol” on page 205. The
settings are the same as for TCP except that the default port is 8050 and SSL also
has the following settings:
Use client authentication: Select this check box to enable client authentication for
the CICS Transaction Gateway. The default is that client authentication is disabled.
When client authentication is enabled, any connection attempted to the ssl: handler
requires the client to present its own Client Certificate (also known as a digital ID).
For information on how to obtain Client Certificates for the clients, see “Using
externally signed certificates under JSSE” on page 100.
For details of the corresponding entry in the configuration file, see clientauth
(“ctg.ini: GATEWAY section” on page 203.)
Key ring file: Enter the server key ring name.
Give either the full path name, or the relative path name of the file. Use either a
forward slash (/) character, or double back slash (\\) characters, as a separator in
the path name on all operating systems. For example:
Chapter 5. Configuration 63

|
|
|
|
/mykeys/jsse/keystore.jks
\\mykeys\\jsse\\keystore.jks
The server key ring consists of a valid x.509 certificate that identifies this server to
connecting clients. This key ring is generated using the SSL tools supplied with
this product.
For details of the corresponding entry in the configuration file, see keyring
(“ctg.ini: GATEWAY section” on page 203).
Key ring password: Enter the password that you specified for the server key ring.
CICS Transaction Gateway writes the password to the configuration file in a form
that prevents a casual observer from easily reading it.
For details of the corresponding entry in the configuration file, see keyringpw
(“ctg.ini: GATEWAY section” on page 203).
Use only these ciphers: Enter a valid cipher suite in the entry field. The entry
must match exactly the name of the cipher suite to be used. Click Add to add the
cipher to the list of ciphers, below the entry field. Click Remove to remove all
selected entries in the ciphers list. See the documentation supplied with your Java
runtime environment for valid cipher suites, or proceed as follows:
1. Remove any entries from the Use only these ciphers list.
2. Save the configuration file.
3. Run ctgstart.
If the SSL protocol is correctly configured, CICS Transaction Gateway displays a
list of valid ciphersuites that Java Client applications can use to connect to the
CICS TG.
If there are entries in the Use only these ciphers list, a Java Client application can
connect to the CICS Transaction Gateway only by using the cipher suites listed. If
the Java Client application does not support any of the cipher suites listed, it
cannot connect.
If there are no entries in the list, a Java Client application can connect using any
available cipher suite.
Use of the ciphersuites=128bitonly parameter is deprecated. If you use the
Configuration Tool to open a configuration file that contains this entry, the entry is
replaced by these cipher suites:
TLS_RSA_WITH_RC4_128_MD5
TLS_RSA_WITH_RC4_128_SHA
TLS_DHE_DSS_WITH_RC4_128_SHA
Cipher suites entered as TLS_ will be converted to SSL_ when the CICS
Transaction Gateway starts. The actual protocol used can be found by checking the
log or trace when a client connects.
For details of the corresponding entry in the configuration file, see ciphersuites
(“ctg.ini: GATEWAY section” on page 203).
Configuring Client daemon settings
64 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
Figure 12. Client settings
Select the Client node to display the Client Configuration panel. The settings map
to the parameters in the CLIENT section of the ctg.ini file. The panel has these
tabs:
Resources
Logging
Default Server
Select the default server from the drop-down list.
Application ID
Enter up to 8 characters, or leave this field with the default value of *.
This value specifies the applid of the CICS Transaction Gateway workstation in the
form in which it will be autoinstalled as a system at the CICS server. The name
must be unique within the CICS server system. The value of * automatically
generates a name that is guaranteed to be unique.
If the client is to be autoinstalled on more than one CICS server and you enter a
specific name for the applid, that name must be unique with respect to all servers
to which it is connected. If the name is not unique, attempts to connect to a server
might be rejected because another client has already been installed using the same
name. If a name of * is used, the client will be known by a different unique name
at each server.
Chapter 5. Configuration 65

If the client is to communicate with a given server over SNA, this applid might be
overridden at the time the client is installed at the server by the Local LU name for
the client.
Maximum buffer size
Enter a number of kilobytes, in the range 4 through 32. The default is 32 KB. If
you enter a value outside the permitted range, the Configuration Tool warns you.
If the value entered is too low, it substitutes the minimum. If the value entered is
too high, it substitutes the maximum. If a non-numeric value is present in the
configuration file, it substitutes the minimum value.
This value specifies the size of the transmission buffers in which application or
terminal data will flow. The value should be large enough to cater for the largest
possible COMMAREA or terminal input/output area (TIOA) to be used. The
maximum COMMAREA size might be less than the Maximum buffer size, because
certain protocols have an overhead of 512 bytes.
Leave this setting at the default unless the CICS Transaction Gateway is running
on a machine that is short of memory.
For details of the corresponding entry in the configuration file, see
MAXBUFFERSIZE (“ctg.ini: CLIENT section” on page 206).
Terminal exit
Enter a character string of between 1 and 4 characters. The default is EXIT.
The string, when entered at a terminal emulator at any time and place where a
transaction name can be entered, causes the terminal emulator to terminate. The
string must not contain any blank characters.
The string is case-sensitive. If a terminal emulator has uppercase translation in its
CICS terminal definition, enter this string in uppercase.
For details of the corresponding entry in the configuration file, see
TERMINALEXIT (“ctg.ini: CLIENT section” on page 206).
Maximum servers
Enter a value in the range 1 through 256. The default is 10. If you enter a value
outside the permitted range, the Configuration Tool warns you. If the value
entered is too low, it substitutes the minimum. If the value entered is too high, it
substitutes the maximum. If a non-numeric value is present in the configuration
file, it substitutes the minimum value.
This value specifies the maximum number of servers that can be accessed
concurrently from the client.
For details of the corresponding entry in the configuration file, see MAXSERVERS
(“ctg.ini: CLIENT section” on page 206).
Maximum requests
Enter a value in the range 1 through 10 000. The default is 256. If you enter a
value outside the permitted range, the Configuration Tool warns you. If the value
entered is too low, it substitutes the minimum. If the value entered is too high, it
substitutes the maximum. If a non-numeric value is present in the configuration
file, it substitutes the minimum value.
66 CICS Transaction Gateway: UNIX and Linux Administration

This value specifies the maximum number of concurrent items that might be
executing on the Client daemon, where an item is one of:
v A request to install or uninstall a terminal emulator
v A request to install or uninstall an EPI terminal
v A transaction invoked by a terminal
v An ECI unit of work
v An ESI unit of work
It is used to detect runaway conditions where an application could, in error,
submit an excessive number of requests to a server. The actual limit might be less
than this setting if other operating system limits (for example, memory constraint
or communication sessions), come into effect.
For details of the corresponding entry in the configuration file, see
MAXREQUESTS (“ctg.ini: CLIENT section” on page 206).
Print command
Enter a character string, from 1 to 256 characters long.
The specified string is a command specific to the operating system under which
the CICS Transaction Gateway is running. When a request to print is received, the
Client daemon generates a temporary print file with a unique name.
The parameter string is appended with the temporary file name, and the resultant
command executed. This allows, for example, print requests to be copied to a file,
directed to a local printer, formatted for inclusion into documentation, and so on.
It is the responsibility of the Print command to delete the temporary print file after
it has finished processing it.
Use a shell script with the Print command (for example, lpr) followed by the
command to delete (rm).
See also the Print file description for more information.
For details of the corresponding entry in the configuration file, see
PRINTCOMMAND (“ctg.ini: CLIENT section” on page 206).
Print file
Enter a character string, 1 to 256 characters long.
This option applies only if you make no entry in the Print command setting.
The specified string identifies a file to which output from print requests received at
the Client daemon is directed. Each print request is appended to the end of the
current file.
This setting acts only as a default. The terminal and print emulators provide
options to override this value.
For details of the corresponding entry in the configuration file, see PRINTFILE
(“ctg.ini: CLIENT section” on page 206).
Chapter 5. Configuration 67

|
|
|
|
|
|
|
|
Code page identifier override
Enter a value indicating a Coded Character Set Identifier (CCSID) to override your
local code page identifier.
Use this setting if your platform has been updated for euro support, and the CICS
Server has euro support. For example, for Latin-1 countries, use a CCSID value of
858 to indicate that the code page 850 includes euro support. For code page 1252,
specify a CCSID value of 5348.
Note:
1. Regardless of the value in the Code page identifier override setting,
cicsterm always displays characters based on the local code page of the
workstation.
2. If you use the CCSID to change the code page identifier, data that is
already stored on the server might be modified when retrieved by the
CICS Transaction Gateway, if it includes characters for which the code
points produce different characters.
3. AIX operating system: On AIX 4.3.2 and above, support for Ja_JP locale
uses CCSID=943. If the CICS Server does not support this CCSID, enter a
code page identifier override of 932, or add the statement ’CCSID=932’
to the Client Section of the configuration file ctg.ini.
For details of the corresponding entry in the configuration file, see CCSID (“ctg.ini:
CLIENT section” on page 206).
Server retry interval
Enter a number between 1 and 3600, to specify the time in seconds between
attempts by the Client daemon to reconnect to a server. The default is 60 seconds.
When the Client daemon becomes aware that a server to which it was connected is
no longer active, it attempts to reconnect to the server 1 second after it becomes
inactive. If it fails it keeps trying, at the interval specified here.
For details of the corresponding entry in the configuration file, see
SRVRETRYINTERVAL (“ctg.ini: CLIENT section” on page 206).
Log terminal installations and deinstallations
Select this check box to log server connection and disconnection events.
For details of the corresponding entry in the configuration file, see
TERMINSTLOGGING (“ctg.ini: CLIENT section” on page 206).
Error and warning log file
Enter the name of the log file to be used for problem diagnosis.
If not specified, the log file name defaults to cicscli.log in the /var/cicscli
subdirectory.
For details of the corresponding entry in the configuration file, see LOGFILE
(“ctg.ini: CLIENT section” on page 206).
Use the same file for information messages
Clear this check box to send information messages to a separate log.
68 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
By default, information messages are logged to the “Error and warning log file” on
page 68; clear the “Use the same file for information messages” on page 68 check
box to enable the “Information log file” field.
This field has no corresponding entry in the configuration file.
Information log file
Enter the name of the file to which information messages will be logged.
By default, information messages are logged to the “Error and warning log file” on
page 68; clear the “Use the same file for information messages” on page 68 field,
and then complete this field, to change the destination. If you do not specify a
path to the file, the log is created in the following directory:
/var/cicscli
For details of the corresponding entry in the configuration file, see LOGFILEINFO
(“ctg.ini: CLIENT section” on page 206).
Changing settings for Client daemon logging
This information describes how to specify a destination for error and other
messages from the Client daemon.
By default error, warning, and informational messages are output to the “Error and
warning log file” on page 68. Terminal installations and deinstallations are not
logged by default. Take the steps below to change the settings.
1. Launch the Configuration Tool and navigate to the Logging tab of the Client
daemon node.
2. Complete the fields on the tab as appropriate. You can choose to:
v Log terminal installations and deinstallations.
v Change the name of the Error and warning log file from the default
cicscli.log.
v Specify a different log for information messages.
3. Save the configuration file.
Related tasks
“Viewing the information log”
This information describes how to view messages that have been output to the
information log.
Related information
“Using the Configuration Tool” on page 50
Viewing the information log
This information describes how to view messages that have been output to the
information log.
1. Determine the location of the information log file. By default, information
messages are output to the “Error and warning log file” on page 68, but the
destination can be changed through the “Information log file” field in the
Configuration Tool.
2. View the file using any standard text editor.
Related tasks
“Changing settings for Client daemon logging”
This information describes how to specify a destination for error and other
messages from the Client daemon.
Chapter 5. Configuration 69

Figure 13. Server settings
Configuring Server settings
Select a server in the navigation panel to display the Server connection panel. The
settings map to the parameters in a Server section of the ctg.ini file.
Multiple identical server definitions are not permitted in the configuration file of
the CICS Transaction Gateway. The combination of fields that identify a server, and
must therefore be unique is as follows:
Protocol
Fields in ctg.ini
TCP/IP
Hostname or IP address and Port.
SNA Partner LU name, Local LU name and Mode name.
TCP62 Partner LU name, Local LU name and Mode name.
This ensures that every connection that the CICS region and the network protocol
see is represented by a unique server definition in the configuration file. If you
have existing Client applications that use different server names to send requests
70 CICS Transaction Gateway: UNIX and Linux Administration

to the same CICS region, you need to write a user exit to redirect requests. This is
demonstrated in sample user exits ecix2.c and epix2.c; see /
samples/samples.txt.
Server name
Enter a name of between 1 and 8 characters. This provides a name that is
independent of the communications protocol for the server, local to the Client
daemon.
Any requests to access the server from ECI, EPI, ESI, or terminal emulators should
use this name.
For details of the corresponding entry in the configuration file, see SECTION
SERVER (“ctg.ini: SERVER section” on page 207).
Description
Enter a description for the server of between 1 and 60 characters. This description
is optional.
This description is returned on EPI or ECI list systems calls.
For details of the corresponding entry in the configuration file, see DESCRIPTION
(“ctg.ini: SERVER section” on page 207).
Initial transaction
Enter a transaction identifier of between 1 and 128 characters.
This string is case-sensitive and identifies the initial transaction (and any
parameters) to be run when the terminal emulator connects to the server. If you do
not enter anything, no initial transaction is run. The first four characters, or the
characters before the first blank in the string are taken as the transaction. The
remaining data is passed to the transaction on its invocation.
Ensure that the transaction does not require terminal input.
For details of the corresponding entry in the configuration file, see
INITIALTRANSID (“ctg.ini: SERVER section” on page 207).
Model terminal definition
Enter a string of between 1 and 16 characters.
The string is case-sensitive and specifies the name of a model terminal definition at
the server, identifying the characteristics of terminals to be autoinstalled from the
client. If the model cannot be located at the server, or you do not enter anything, a
default terminal definition is used. This default is server-specific.
The interpretation of the Model terminal definition setting is server-specific. For
example, for a TXSeries for AIX server, the value is 1 to 16 characters, and is the
DevType for a CICS terminal definition entry to be used as the model.
For details of the corresponding entry in the configuration file, see MODELTERM
(“ctg.ini: SERVER section” on page 207).
Chapter 5. Configuration 71

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Use upper case security
Select this check box to specify that the CICS Transaction Gateway converts to
uppercase any user ID or password from an ECI application or from a user
prompt. This setting is disabled by default.
For details of the corresponding entry in the configuration file, see
UPPERCASESECURITY (“ctg.ini: SERVER section” on page 207).
Network protocol
Select the protocol to be used for the server connection from the list:
v TCP/IP
v TCP62
v SNA
The protocol settings on the panel change according to the protocol you select.
Server idle timeout (mins)
Enter an integer in the range 1 through 1080, to specify in minutes the period of
inactivity after which the connection between the Client daemon and the CICS
server is closed. A value of 0 means that no timeout is applied. The default value
is 0.
The field is available if one of the following network protocols is selected:
v TCP/IP
v SNA
The Server idle timeout (mins) period is counted from when the number of
outstanding conversations (units of work) on the connection is zero. The
connection is automatically reestablished when a Client application sends the next
ECI, EPI or ESI request.
When a server connection times out, the Client daemon behaves as if the cicscli
-x= command had been issued. In particular, any value specified in
the “Server retry interval” on page 68 configuration field is ignored, and no
attempt is made to reestablish the connection. The “Server retry interval” on page
68 setting is re-enabled if the connection is reestablished.
For details of the corresponding entry in the configuration file, see
SRVIDLETIMEOUT (ctg.ini: SERVER section `sectionserver). If the network
protocol for the server in question is not supported for this field, the Client
daemon ignores any entry in the configuration file for the Server idle timeout
(mins) field.
Related information
“Shutting down the Client daemon normally” on page 134
TCP/IP settings
Hostname or IP address: Enter the character or numeric TCP/IP identifier for the
host on which the CICS server is running. For example, cicssrv2.company.com
(host name) or 192.113.36.200 (IP Address).
Host names are mapped to IP addresses either by the name server or in the hosts
system file. It is better to use a host name in case the IP address changes.
The hosts system file is in the /etc directory.
72 CICS Transaction Gateway: UNIX and Linux Administration

|
|
For details of the corresponding entry in the configuration file, see NETNAME
(“ctg.ini: SERVER section” on page 207).
Port: Enter a numeric value in the range 0 through 65 535 defining the port
number at the server to which the Client daemon should connect. The default
value is 0. If you enter a value outside the permitted range, the Configuration Tool
warns you. If the value entered is too low, it substitutes the minimum. If the value
entered is too high, it substitutes the maximum. If a non-numeric value is present
in the configuration file, it substitutes the minimum value.
A value of 0 indicates that the services system file should be used to locate the
port number for the CICS service using the TCP protocol.
The services system file is in the /etc directory.
If no entry can be located in the services system file, a value of 1435 is assumed.
This is the port assigned to the Client daemon in the TCP/IP architecture.
For details of the corresponding entry in the configuration file, see PORT (“ctg.ini:
SERVER section” on page 207).
Connection timeout: Enter a value in the range 0 through 3600, specifying the
maximum time in seconds that establishing a connection is allowed to take; the
default value of 0 means that no limit is set by the Client daemon. If you enter a
value outside the permitted range, the Configuration Tool warns you. If the value
entered is too low, it substitutes the minimum. If the value entered is too high, it
substitutes the maximum. If a non-numeric value is present in the configuration
file, it substitutes the minimum value.
A timeout occurs if connection establishment takes longer than the specified time.
The TCP/IP socket is closed and the return code passed back to the client
application is either ECI_ERR_NO_CICS or CICS_EPI_ERR_FAILED.
Cleanup processing happens after a timeout only if the server has support for this
function installed.
For details of the corresponding entry in the configuration file, see
CONNECTTIMEOUT (“ctg.ini: SERVER section” on page 207).
Send TCP/IP KeepAlive packets: Select this check box if you want TCP/IP to
periodically send keepalive messages to the server to check the connection. The
CICS Transaction Gateway uses the interval specified by your operating system.
For details of the corresponding entry in the configuration file, see
TCPKEEPALIVE (“ctg.ini: SERVER section” on page 207).
SNA settings
Note: Use the Configuration Tool to configure SNA on the AIX, Linux and Solaris
operating systems.
Use LU alias names: Select this check box to use LU alias names.
LU names are always aliases on UNIX and Linux operating systems. This setting is
ignored but treated as if it is set.
Chapter 5. Configuration 73

Partner LU name: Enter the LU name of the server as it is known to the APPC
configuration at the Client daemon.
Enter an alias name of eight characters or less.
Local LU name: Enter the name of a local LU to be used when connecting to the
server. The same LU can be used for all server connections.
Enter an alias name of eight-characters or less.
For details of the corresponding entry in the configuration file, see
LOCALLUNAME (“ctg.ini: SERVER section” on page 207).
Mode name: Enter between 1 and 8 characters specifying the mode name to be
used when connecting to the server.
Enter * if you want the mode name to be filled with spaces.
TCP62 settings
Hosts file: When configuring a TCP62 CICS server, unless you are using a
TCP/IP domain name server you must also update the local hosts file. The path to
the file is:
/etc/hosts
The file maps IP addresses to host names. Keep each entry on a separate line.
Entries are in this form:
192.113.36.200 CICSA.NYEBO.myplace.ibm.com
Each element of the entry is explained below:
192.113.36.200
The IP address of the CICS system. It must start in column one, and be
separated from the rest of the entry by at least one space.
CICSA.NYEBO
The Partner LU name, in reverse order. In the example above, NYEBO.CICSA is
the Partner LU name, as entered in the Configuration tool.
myplace.ibm.com
The Anynet domain name suffix.
Partner LU name: Enter the fully-qualified LU name of the CICS region as it is
known in VTAM. This is the applid of the CICS region preceded by the SNA
network name, for example ABC3XYZ4.PQRS1234.
For details of the corresponding entry in the configuration file, see NETNAME and
NETNAME (“ctg.ini: SERVER section” on page 207.)
Local LU name or template: Enter a real LU name or a template for the name of
a local LU to be used when connecting to the CICS server.
A template contains replacement characters, that is, asterisks (*), and is used to
generate an LU name dynamically. For example, a template of CTS8BC** indicates
that a name must be dynamically generated to replace the two asterisks. An
algorithm based on the template, IP address mask, and the workstation IP address,
is used to create a unique Local LU name of, for example, CTS8BC38.
74 CICS Transaction Gateway: UNIX and Linux Administration

With dynamic name generation for the Local LU name, you can use the same
configuration on all CICS Transaction Gateway machines because different Local
LU names are generated on the basis of the IP address of the client machine.
Therefore, you do not have to define multiple LUs within VTAM.
For each asterisk the algorithm uses 5 bits from the IP address. The CICS
connection autoinstall program (DFHZATDY) uses the last four characters of the
LU name to generate the connection name, which has to be unique within the
CICS region. Follow these rules to ensure that the dynamically generated TCP62
LU names, and the CICS connection names are unique:
v Set the IP address mask for LU name template (optional) field to be equal to
the TCP/IP subnet mask. The subnet is the mask that is applied to an IP address
to determine which bits in an IP address are to be used for local addresses (that
is, addresses on the local subnet) and which bits are to be used for the network
address (that is, on the wider network). A subnet mask of 255.255.254.0 (or in
binary 11111111.11111111.11111110.00000000) has 8 bits free in the fourth byte (0)
and 1 bit free in the third byte (254), giving a total of 9 free bits. There are 2 9
or
512 unique network addresses available in this subnet.
v Set the Local LU name or template field to have four or less trailing asterisks.
Table 4 shows how many asterisks to include to accommodate all the unique IP
addresses in your subnet.
Table 4. Values required to generate unique LU names
Number of free bits in the
IP address mask
Number of asterisks needed Maximum number of
unique names
16-20 4 (XXXX****) 1 048 576
11-15 3 (XXXXX***) 32 768
6-10 2 (XXXXXX**) 1024
1-5 1 (XXXXXXX*) 32
There are 32 different values that the algorithm can use for each asterisk.
Generating 32 different values requires 5 unique bits (2 5
=32). This means that up
to 5 bits are used for each asterisk, starting from the right. Based upon this fact,
Table 4 helps you determine the minimum number of asterisks to use in your
template name to guarantee generated LU names will be unique within your
subnet.
For example, a subnet mask of 255.255.254.0 has 9 bits free for local network
addresses, and therefore a possible 2 9
(512) unique IP address in the subnet. Two
asterisks can accommodate up to 2 10
combinations (1024); more than enough to
cover the 512 unique IP addresses in the subnet.
To use a template, also configure CICS and VTAM as follows:
CICS Set APPC CONNECTION to autoinstall
VTAM
Enable dynamic partner LUs (set DYNLU=YES)
For details of the corresponding entry in the configuration file, see
LOCALLUNAME (“ctg.ini: SERVER section” on page 207).
IP address mask for LU name template (optional):
Chapter 5. Configuration 75

If you are using dynamic LU names, set this to the hexadecimal version of your IP
subnet mask. To determine your IP subnet mask, issue a command like the
following:
ifconfig
See the description of Local LU name or template for more information. This
parameter is ignored if Local LU name is not a template. The default is 00000000.
For details of the corresponding entry in the configuration file, see
LUIPADDRESSMASK (“ctg.ini: SERVER section” on page 207).
Mode name: Enter between 1 and 8 characters specifying the mode name to be
used when connecting to the server.
Enter * if you want the mode name to default to TCP62.
Use the Maximum logical SNA sessions, Maximum SNA RU size, and SNA
pacing size settings in the Advanced TCP62 section to define the mode values
specified for the Mode name on your CICS server.
For details of the corresponding entry in the configuration file, see the
MODENAME and MODENAME entries in “ctg.ini: SERVER section” on page 207
Common TCP62 settings
Fully qualified CP name or template: Enter a fully-qualified CP name, or a
template for the fully-qualified CP name, of the node to be started.
If you enter a template, you must fill in the IP address mask for CP name
(optional) field.
A template contains replacement characters, that is, asterisks (*), and is used to
generate a CP name dynamically. For example, a template of USIBMJKA.CP62****
indicates that a name must be dynamically generated to replace the four asterisks.
An algorithm based on the template, IP address mask and the workstation IP
address, is used to create a unique CP name of, for example,
USIBMJKA.CP62AH38.
With dynamic name generation for the CP name, you can use the same
configuration on all CICS Client machines because different CP names are
generated on the basis of the IP address of the client machine. Therefore, you do
not have to define multiple CPs to VTAM.
If several hundred clients are to use dynamic CP name generation, you should
have more template replacement characters in your template, for example,
USIBMJKA.CP******.
The net ID part (the first part) of the template must not contain any template
replacement characters.
For details of the corresponding entry in the configuration file, see CPNAME
(“ctg.ini: CLIENT section” on page 206).
76 CICS Transaction Gateway: UNIX and Linux Administration

IP address mask for CP name (optional): Enter an IP address mask with the
most significant byte first. This must be a hexadecimal number, for example,
FFFF8080.
This address mask is used in dynamic CP name generation. See the description of
Fully qualified CP name or template for more information.
This parameter is ignored if Fully qualified CP name or template is not a
template. The default is 00000000.
For details of the corresponding entry in the configuration file, see
CPIPADDRESSMASK (“ctg.ini: CLIENT section” on page 206).
AnyNet domain name suffix: Enter the AnyNet domain name suffix. This
parameter is used with the partner (Partner LU name) to determine the IP address
of the host associated with that LU.
For example, if the domain name suffix is sna.ibm.com and the partner LU name is
NETID.LUA, a gethostbyname call is issued for host name LUA.NETID.sna.ibm.com to
obtain the IP address of the node that has the LU name NETID.LUA.
The CICS Transaction Gateway uses the AnyNet domain name suffix, in
conjunction with the fully qualified Partner LU name, to resolve the IP address of
each connected server. The AnyNet domain name suffix can be an arbitrary value
if the local hosts file is used to resolve host names. However, if you use a DNS
server to look up host names, the combination of the AnyNet domain name suffix
and the SNA network name must correspond to a real IP domain, so that the host
name (corresponding to the Partner LU name) can be found in the DNS server.
A configuration file can contain only one value for the AnyNet domain name
suffix. To connect to more than one CICS region from the same CICS Transaction
Gateway over TCP62, define a server for each CICS region, using a common
AnyNet domain name suffix, and unique values for the Partner LU name. Make an
entry for each server in the local hosts file, mapping the server’s IP address to the
host name. See “Hosts file” on page 74 for information on how IP addresses map
to host names.
For details of the corresponding entry in the configuration file, see
DOMAINNAMESUFFIX (“ctg.ini: CLIENT section” on page 206).
TCP62 port: Enter a number in the range 0 through 65 535 , to set the port
number on the server to which the Client daemon connects. The default value is 0.
This means that the Client daemon uses port 397, the default port for the TCP/IP
service MPTN. If you enter a value outside the permitted range, the Configuration
Tool warns you. If the value entered is too low, it substitutes the minimum. If the
value entered is too high, it substitutes the maximum. If a non-numeric value is
present in the configuration file, it substitutes the minimum value.
On UNIX and Linux operating systems, only a root user can access ports in the
range 1 to 1023. This means that if CICS Transaction Gateway is started by a user
who has not logged in as root, it cannot use the default port for TCP62. To use
TCP62 from a user other than root, set TCP62 port to a value outside the range 1 to
1023.
The port number is the port number that AnyNet is configured to use.
Chapter 5. Configuration 77

For details of the corresponding entry in the configuration file, see TCP62PORT
(“ctg.ini: SERVER section” on page 207).
Remote node inactivity poll interval (s): Enter a number in the range 0 through
65 535 to specify the time that the Client daemon waits before polling inactive
connections. The default value is 60 seconds. A value of 0 turns off polling. If you
enter a value outside the permitted range, the Configuration Tool warns you. If the
value entered is too low, it substitutes the minimum. If the value entered is too
high, it substitutes the maximum. If a non-numeric value is present in the
configuration file, it substitutes the minimum value.
The Client daemon polls inactive connections by sending MPTN KeepAlive
datagrams by User Datagram Protocol (UDP) to the CICS server. If you run a
firewall, configure it to allow UDP packets. If the Client daemon receives no
response after it has sent several datagrams, it closes the connection with CICS. For
more information on MPTN KeepAlives, see an Anynet publication such as Anynet:
Guide to SNA over TCPIP, SC31-8578-00.
For details of the corresponding entry in the configuration file, see
REMOTENODEINACTIVITYPOLLINTERVAL (“ctg.ini: CLIENT section” on page
206).
Advanced TCP62 settings
Maximum logical SNA sessions: Enter a value in the range 1 through 255. The
default value is 8. If you enter a value outside the permitted range, the
Configuration Tool warns you. If the value entered is too low, it substitutes the
minimum. If the value entered is too high, it substitutes the maximum. If a
non-numeric value is present in the configuration file, it substitutes the minimum
value.
This parameter defines the maximum number of SNA sessions for the configured
TCP62 mode. The number of concurrent requests to a configured CICS server is
limited by the SNA session limits in the TCP62 Mode. The SNA session limits in
the Mode are negotiated during the CNOS exchange between the CICS Transaction
Gateway and the CICS server when the TCP62 connection is started.
For details of the corresponding entry in the configuration file, see
SNASESSIONLIMIT (“ctg.ini: SERVER section” on page 207).
Maximum SNA RU size: Enter a value in the range 256 through 4096. The
default value is 1024; for large COMMAREAs consider increasing it to the
maximum. If you enter a value outside the permitted range, the Configuration Tool
warns you. If the value entered is too low, it substitutes the minimum. If the value
entered is too high, it substitutes the maximum. If a non-numeric value is present
in the configuration file, it substitutes the minimum value.
This parameter specifies the maximum size of the request or response units sent
over sessions.
For details of the corresponding entry in the configuration file, see
SNAMAXRUSIZE (“ctg.ini: SERVER section” on page 207)
SNA pacing size: Enter a value in the range 0 through 63. You are recommended
to use the default value of 8. If you enter a value outside the permitted range, the
Configuration Tool warns you. If the value entered is too low, it substitutes the
78 CICS Transaction Gateway: UNIX and Linux Administration

minimum. If the value entered is too high, it substitutes the maximum. If a
non-numeric value is present in the configuration file, it substitutes the minimum
value.
This parameter specifies how many request units can be sent before receiving a
pacing response.
For details of the corresponding entry in the configuration file, see
SNAPACINGSIZE (“ctg.ini: SERVER section” on page 207).
Trace settings
To configure the trace settings, select the Trace Settings option from the Tools
menu.
Trace Settings
Select check boxes to specify the Gateway daemon and Client daemon components
that will be traced when tracing is turned on.
Enable Gateway daemon trace and select all Client trace components
Enable Gateway daemon trace and select all Client daemon components.
Client API level 1
The client API layer (level 1).
Client API level 2
The client API layer (level 1 and 2).
CICSCLI command line
The cicscli command interface.
CICSTERM and CICSPRINT
cicsterm and cicsprnt emulators.
CPP classes
The C++ class libraries.
Client daemon
The Client daemon.
Transport layer
Interprocess communication.
Enable Gateway daemon trace on startup
The CICS Transaction Gateway.
Protocol drivers level 1
Protocol drivers (for example, TCP). This traces data sent and received and
provides supplementary information about failures.
Protocol drivers level 2
This traces internal flows through the protocol drivers and interactions
with other software components. It is currently only supported by the
CCLTCP62 protocol driver.
You can also use the -m parameter of the cicscli command to specify trace
components (excluding the Gateway daemon). This overrides any settings in the
configuration file. For more information about the cicscli command, see “The cicscli
command” on page 133.
If you enable tracing without specifying the components in either the cicscli
command or in ctg.ini, a default set of components is traced:
Chapter 5. Configuration 79

v Protocol drivers
v The Client daemon
v Client API level 1
Selecting any of the check boxes in the Configuration Tool overrides the default set
of components.
For details of the corresponding entry in the configuration file, see trace (“ctg.ini:
GATEWAY section” on page 203) and TRACE (“ctg.ini: CLIENT section” on page
206).
Gateway trace file
Enter the path name of a trace file to which Gateway trace messages will be
written, if tracing is enabled. If you do not complete this field, the trace is written
to stderr. If you specify a name without a path, trace messages are written to the
following directory:
/bin
No trace will be written if the CICS Transaction Gateway does not have permission
to write to the file you specify.
You can also specify a trace file using the tfile option on the ctgstart command.
The trace file is overwritten (not appended to) each time the CICS Transaction
Gateway starts.
Performance: Turning on the Gateway trace has a significant impact on
performance. It is not recommended that Gateway trace is enabled
in a production environment.
For details of the corresponding entry in the configuration file, see tfile (“ctg.ini:
GATEWAY section” on page 203).
Gateway trace file wrap size (KB)
Enter a value in the range 0 through 1 000 000.
This value specifies the size in kilobytes to which the gateway trace file will grow.
Once the file reaches this size, subsequent trace entries continue to be written from
the beginning of the file.
v The default value of 0 disables wrapping.
v If you enter a value in the range 1 through 39, the CICS Transaction Gateway
uses a value of 40 instead, to guarantee an adequate minimum trace size.
For details of the corresponding entry in the configuration file, see tfilesize
(“ctg.ini: GATEWAY section” on page 203).
Client trace file
Enter the path name of a trace file to which Client trace messages will be written,
if tracing is enabled.
You do not have to enter an extension for the file name, because a file of type .BIN
is always generated (or .WRP if the trace file wraps).
If no path is specified, the trace is written as follows:
80 CICS Transaction Gateway: UNIX and Linux Administration

var/cicscli/cicscli.bin
To minimize any performance impact, the trace file is written out in binary format.
To read it, convert the file to ASCII using the cicsftrc command.
For more information about tracing, see “Tracing” on page 155.
For details of the corresponding entry in the configuration file, see TRACEFILE
(“ctg.ini: CLIENT section” on page 206).
Client trace file wrap size (KB)
Enter a value in the range 0 through 2 000 000.
If you use the memory mapped tracing option (cicscli -b), the size of the trace files
is determined by this field, which specifies the total amount of space in KB
reserved for trace data files. Subsequent trace entries will continue to be written
from the beginning of the file. Client trace file wrap size (KB) must be greater
than 0 if memory mapped tracing is to be used; the default value of 0 disables
wrapping. If its value is between 1 and 99, a value of 100 is used instead to
guarantee an adequate minimum trace size.
For details of the corresponding entry in the configuration file, see
MAXWRAPSIZE (“ctg.ini: CLIENT section” on page 206).
Help on starting JNI trace
Use one of the following methods to enable JNI trace:
v Set the following environment variables before you start the CICS Transaction
Gateway:
CTG_JNI_TRACE
Use this environment variable to set the name of the JNI trace file. This
environment variable only defines the name of the JNI trace file; it does not
enable trace. JNI trace is output as plain text, and there is no requirement to
use a particular extension for the file name.
CTG_JNI_TRACE_ON
Set this environment variable to YES (case-insensitive) to enable JNI trace
when the CICS Transaction Gateway is started.
v While the CICS Transaction Gateway is running, use the system administration
functions. See “Administering your system” on page 126 for details of how to
enable JNI trace dynamically.
If the previous methods are not suitable, use one of the following methods:
v For Java Client applications running in local mode, use Java to launch your
application and set the system property gateway.T.setJNITFile, as shown in the
following example:
java -Dgateway.T.setJNITFile=filename application
where
– filename is the name of the file to which trace output is to be sent
– application is the application to launch
v When you start the CICS Transaction Gateway, issue the command
ctgstart -j-Dgateway.T.setJNITFile=filename
Chapter 5. Configuration 81

where filename is the name of the file to which trace output is to be sent. If you
do not specify a full path to the file, the location is /bin.
You cannot enable JNI trace through the Configuration Tool.
Applying your changes to the system
You must restart the Client daemon and the Gateway daemon for any changes to
the configuration file to take effect.
J2EE setup and configuration
This topic discusses the administration of CICS J2EE resource adapters. The CICS
Transaction Gateway supplies the following, in the /deployable
directory:
v An adapter for ECI (cicseci.rar)
v An adapter for EPI (cicsepi.rar)
Transaction management models
cicseci.rar
This resource adapter provides LocalTransaction support when deployed on
any supported J2EE application server. Local transactions are not supported
when using WebSphere Application Server for z/OS with CICS TG on z/OS in
local mode, as the resource adapter provides global transaction support in
conjunction with MVS RRS.
cicseciXA.rar
This provides both XATransaction and LocalTransaction support when
deployed on any supported J2EE application server connecting to a remote
CICS TG for z/OS. It also provides global transaction support when using
WebSphere Application Server for z/OS with a CICS TG on z/OS in local
mode.
In order to provide for different transactional qualities of service for J2EE
applications, it is possible to deploy both CICS resource adapters into the same
J2EE application server. When multiple resource adapters are used in the same
J2EE application server, they must all be at the same version.
Deploying CICS resource adapters
Before you can use a J2EE resource adapter in a server runtime environment you
must set its deployment parameters. In a managed environment you set these
when you deploy the resource adapter to your server. For instructions on how to
do this consult your server’s documentation. For information about nonmanaged
environments, see CICS Transaction Gateway: Programming Guide.
CICS resource adapters are provided in standard resource adapter modules ready
for deployment into a J2EE server environment. They can be packaged in J2EE
applications along with other components such as Enterprise Beans, and used to
create larger, more complex systems.
Deployment parameters for the ECI resource adapters
This section describes the available deployment parameters for the ECI resource
adapters, and their effect on the final deployed resource adapter. The tools used to
82 CICS Transaction Gateway: UNIX and Linux Administration

configure these parameters are server-specific. The default value is shown where
appropriate. If a parameter is required this is indicated, otherwise the parameter is
optional.
ConnectionURL
The URL of the CICS Transaction Gateway with which the resource
adapter will communicate. The URL takes the form protocol://address.
This parameter is required; these protocols are supported:
tcp
ssl
local
So, for example, you might specify a URL of tcp://ctg.business.com For
the local protocol simply specify local:.
PortNumber
The port on which the CICS Transaction Gateway is running. The default
value is 2006. This parameter is not relevant if you are using the local
protocol.
ServerName
The name of the CICS server to connect to for all interactions through this
resource adapter. If this parameter is left blank the default server will be
used (see “Default Server” on page 65). This name is defined in the CICS
Transaction Gateway configuration file. To use multiple servers within an
environment you must deploy several Connection Factories, each with a
different ServerName attribute. Each Connection Factory can use the same
Resource Adapter.
SocketConnectTimeout
The maximum time in milliseconds that a Java Client application will try
to open a socket connection to a remote Gateway daemon. The default
value 0 means no timeout is applied. The timeout is ignored for attempts
to connect to a local Gateway.
TranName
The name of the CICS Transaction under which you want all programs
started by the resource adapter to run. The called program runs under a
mirror transaction, but is linked to under the tranName transaction name.
This name is available to the called program for querying the transaction
ID.
Setting the tranName in the ECIInteractionSpec overrides the value as set
at deployment (or on the ManagedConnectionFactory, if nonmanaged).
The TranName is equivalent to eci_transid. It does not affect the
transaction under which the mirror program runs, but it can be seen in the
exec interface block (EIB). When this option is used the remote program
runs under the default mirror transaction id CSMI, but the EIBTRNID field
contains the eci_transid value.
TPNName
The name of the CICS TPN Transaction under which you want all
programs started by the resource adapter to run. TPNName takes
precedence if both TranName and TPNName are specified. If the
TPNName is set on the ECIInteractionSpec, this overrides any values set at
deployment time (or on the ManagedConnectionFactory, if nonmanaged).
The TPNName is equivalent to eci_tpn; it specifies a transaction under
which the CICS mirror program will run. This option is like the TRANSID
Chapter 5. Configuration 83

option in an EXEC CICS LINK command. A transaction definition in CICS
for this TRANSID must point to the DFHMIRS program.
UserName
The CICS user ID to be used if no other security credentials are available.
See the J2EE section in the CICS Transaction Gateway: Programming Guide for
more information.
A LogonLogoff class is required if:
v The requested terminal is sign-on capable, or
v The CICS Server does not support sign-on capable terminals (for
example, CICS Transaction Server for iSeries)
Password
The password for the CICS user ID defined above.
ClientSecurity
The fully-qualified name of the ClientSecurity class to use in each
interaction with CICS. This parameter is optional; if no value is given, no
ClientSecurity class is used. For more information on what ClientSecurity
classes are used for, and how to write them, see CICS Transaction Gateway
security classes in the Java chapter of the CICS Transaction Gateway
Programming Guide.
ServerSecurity
The fully-qualified name of the ServerSecurity class to use in each
interaction with CICS. This parameter is optional; if no value is given, no
ServerSecurity class is used. For more information on what ServerSecurity
classes are used for, and how to write them, see CICS Transaction Gateway
security classes in the Java chapter of the CICS Transaction Gateway
Programming Guide.
KeyRingClass
The fully-qualified name of the SSL key ring to use. This applies only
when using the SSL protocol.
KeyRingPassword
The password for the key ring defined in KeyRingClass. Because it is
linked to KeyRingClass, it is also optional, and applies only to the SSL
protocol.
TraceLevel
The level of trace to be output by the resource adapter. For more details on
trace levels and tracing see “Tracing” on page 87.
As well as these user-definable properties, the ECI resource adapters have a set of
predefined attributes that each deployed resource adapter will inherit. These
properties are defined in the J2EE/CA specification and are as follows:
Transaction Support
The cicseci resource adapter’s transactional support is defined as
LocalTransaction.
Re-Authentication Support
The ECI resource adapters support re-authentication. This is the ability to
change the security credentials when a connection is requested from the
server and an already existing one is allocated without having to
disconnect and reconnect to the EIS. This improves performance.
84 CICS Transaction Gateway: UNIX and Linux Administration

Deployment parameters for the EPI resource adapter
The EPI resource adapter has the following deployment parameters. The tools used
to configure these parameters are server-specific. The default value is shown where
appropriate. If a parameter is required this is indicated, otherwise the parameter is
optional.
ConnectionURL
The URL of the CICS Transaction Gateway with which the resource
adapter will communicate. The URL takes the form protocol://address.
This parameter is required; these protocols are supported:
tcp
ssl
local
So, for example, you might specify a URL of tcp://ctg.business.com For
the local protocol simply specify local:.
PortNumber
The port on which the CICS Transaction Gateway is running. The default
value is 2006. This parameter is not relevant if you are using the local
protocol.
ServerName
The name of the CICS server to connect to for all interactions through this
resource adapter. If this parameter is left blank the default server will be
used (see “Default Server” on page 65). This name is defined in the CICS
Transaction Gateway configuration file. To use multiple servers within an
environment you must deploy several Connection Factories, each with a
different ServerName attribute. Each Connection Factory can use the same
Resource Adapter.
SocketConnectTimeout
The maximum time in milliseconds that a Java Client application will try
to open a socket connection to a remote Gateway daemon. The default
value 0 means no timeout is applied. The timeout is ignored for attempts
to connect to a local Gateway.
UserName
The CICS user ID to be used if no other security credentials are available.
See the J2EE section in the CICS Transaction Gateway: Programming Guide for
more information.
A LogonLogoff class is required if:
v The requested terminal is sign-on capable, or
v The CICS Server does not support sign-on capable terminals (for
example, CICS Transaction Server for iSeries)
Password
The password for the CICS user ID defined above.
ClientSecurity
The fully-qualified name of the ClientSecurity class to use in each
interaction with CICS. This parameter is optional; if no value is given, no
ClientSecurity class is used. For more information on what ClientSecurity
classes are used for, and how to write them, see CICS Transaction Gateway
security classes in the Java chapter of the CICS Transaction Gateway
Programming Guide.
ServerSecurity
The fully-qualified name of the ServerSecurity class to use in each
Chapter 5. Configuration 85

interaction with CICS. This parameter is optional; if no value is given, no
ServerSecurity class is used. For more information on what ServerSecurity
classes are used for, and how to write them, see CICS Transaction Gateway
security classes in the Java chapter of the CICS Transaction Gateway
Programming Guide.
KeyRingClass
The fully-qualified name of the SSL key ring to use. This applies only
when using the SSL protocol.
KeyRingPassword
The password for the key ring defined in KeyRingClass. Because it is
linked to KeyRingClass, it is also optional, and applies only to the SSL
protocol.
SignonType
The EPI resource adapter allows you to define whether the CICS terminals
used by the resource adapter are sign-on capable. Enter one of the
following:
0 Sign-on capable terminal (default)
1 Sign-on incapable terminal
For information about sign-on capability, see “Sign-on capable and sign-on
incapable terminals” on page 109.
Encoding
The Java Encoding to use when creating 3270 data streams. The encoding
will be converted to the appropriate CCSID. See the appendix in the CICS
Transaction Gateway: Programming Reference for a list of supported
encodings. Ensure that your CICS Server supports the CCSID for the given
encoding.
LogonLogoffClass
The fully-qualified name of the Java Class that provides the logic to log on
to a CICS Server using sign-on transactions. This property is mandatory for
sign-on capable terminals and for CICS servers that do not support sign-on
capability (such as CICS Transaction Server for iSeries). See CICS
Transaction Gateway: Programming Guide for information about LogonLogoff
classes.
DeviceType
The Terminal Model type, as defined in CICS, to be used by this resource
adapter.
ReadTimeout
The maximum time a CICS server waits for a response from a user or J2EE
component when taking part in a conversational transaction. Acceptable
values for this parameter are:
0 No timeout.
1– 3600
Time in seconds.
InstallTimeout
The timeout value for terminal installation on CICS. The acceptable values
for this parameter are as follows:
0 No timeout.
86 CICS Transaction Gateway: UNIX and Linux Administration

1– 3600
Time in seconds.
TraceLevel
The level of trace to be output by the resource adapter. For more details on
trace levels and tracing see “Tracing.”
As well as these user-definable properties, the EPI resource adapter has a set of
predefined attributes that each deployed resource adapter will inherit. These
properties are defined in the J2EE/CA specification and are as follows:
Transaction Support
The EPI resource adapter is nontransactional. It can be used within
transactional contexts, but does not react to commit or rollback requests.
Re-Authentication Support
The EPI resource adapter supports re-authentication. This is the ability to
change the security credentials when a connection is requested from the
server and an already existing one is allocated, without having to
disconnect and reconnect to the EIS. This improves performance. A
LogonLogoff class is required if the terminal requested is SignonCapable,
or if the CICS Server does not support sign-on capable terminals (such as
CICS Transaction Server for iSeries).
Tracing
To help you in problem determination with any J2EE resource adapter applications
that use the CICS resource adapters, a detailed tracing function is provided in both
the ECI and EPI resource adapters. The CICS resource adapters support four levels
of trace:
0 No trace messages
1 Exception tracing only (default level)
2 Exception and method entry/exit trace messages
3 Exception, method entry/exit and debug trace messages
To provide more control over tracing, these system properties are available:
com.ibm.connector2.cics.tracelevel
This allows you to override the deployed trace level for the resource
adapters without having to redeploy or deploy another CICS resource
adapter.
com.ibm.connector2.cics.dumpoffset
The offset into a byte array that a hex dump will start at.
com.ibm.connector2.cics.dumplength
The maximum length of data displayed in a hex dump.
com.ibm.connector2.cics.outputerr
Declaring this directive sends trace output to standard error, if no other
trace location has been specified either by the J2EE server, or by the
application developer working in a nonmanaged environment. In other
circumstances the provided logwriter takes precedence.
These are JVM System properties that can be passed to the JVM on startup. The
com.ibm.connector2.cics.tracelevel option is equivalent to the managed
environment property ″tracelevel″ which is set as a custom property on the
connection factory.
Chapter 5. Configuration 87

The ConnectionManager used by your environment controls the location to which
trace is output. In a managed environment an option should be provided to allow
you to set the path of the file that will be used for storing trace. Depending on
how your environment allocates ConnectionManagers to resource adapters this file
might contain messages from other resource adapters using the same
ConnectionManager.
When you deploy the CICS resource adapters into your environment, security
restrictions are set up to allow access to the local file system for the purpose of
writing trace files. The permissions used restrict access to this path:
${user.home}${file.separator}IBM${file.separator}CTG${file.separator}-
This might map to:
/home/ctguser/IBM/CTG/-
Therefore, when setting the name and path of the trace file in your J2EE
environment, use a location below this directory structure to store your trace.
Otherwise the resource adapters will not have security permissions to write to the
file.
The CICS Transaction Gateway logging facility
This section discusses how to configure log messages. Log messages can be routed
to either the console or a file, through one of two log streams, the information log
and the error log. Each log stream can have its own end point and is therefore
configured separately. You can do the following actions:
v Specify whether information and error messages should be logged to the
console, or to a file.
v Specify the name of the files to which messages are logged.
v Specify how many archived logged files to keep.
Setting up the environment for CICS Transaction Gateway
logging
Use the Configuration Tool to set the following fields:
If you set the maximum size field for a log, also set the number of archived logs to
keep field to be greater than 1. Do not set a maximum file size and set the number
of archived logs to 1. This results in error message CTG8143E being issued and all
messages being re-directed to the console. No log file is created.
Error log
Action Set this field
Set the destination for error
messages (file or console)
“Error and warning log destination” on page 58
Set the file name for error messages “Error log file name” on page 58
Set the maximum size of error log
files
Set the number of archived error
logs to keep
88 CICS Transaction Gateway: UNIX and Linux Administration
“Error log maximum size (KB)” on page 58
“Maximum number of archived error log files” on
page 58

Information log
Action Set this field
Set the destination for information
messages (file or console)
Set the file name for information
messages
Set the maximum size of
information log files
Set the number of archived
information logs to keep
Sample configuration and mapping files
“Information log destination” on page 59
“Information log file name” on page 59
“Information log maximum size (KB)” on page 59
“Maximum number of archived information log files”
on page 59
The following files are supplied in the /bin subdirectory:
ctgsamp.ini
A sample configuration file. (The default configuration file name is ctg.ini.)
cicskey.ini
The keyboard mapping file.
cicskeysamp.ini
A sample keyboard mapping file.
cicscol.ini
The color mapping file.
cicscolsamp.ini
A sample color mapping file.
It is recommended that you create your own customized versions of these files
with different names, because installing service updates might overwrite the files
and cause any customization to be lost.
Reference your customized files through the following environment variables:
File Environment variable
configuration file
CICSCLI
keyboard mapping file
CICSKEY
color mapping file
CICSCOL
Keyboard mapping for cicsterm
The keyboard mapping for terminal emulator operation is defined in a keyboard
mapping file. A sample key mapping file is supplied with your CICS Transaction
Gateway; see “Sample configuration and mapping files” for details. It is
recommended that you create your own customized mapping file.
The keyboard mapping file can be specified by:
v The -k option of the cicsterm command, which identifies a keyboard mapping
file with a particular terminal (see “cicsterm command reference” on page 145).
Chapter 5. Configuration 89

v The CICSKEY environment variable. For example:
export CICSKEY=/var/cicscli/mykeys.ini
If you do not specify otherwise, a file name of cicskey.ini in the /bin
subdirectory is assumed.
You can change the keyboard mapping file at any time, although changes do not
take effect until the next time the terminal emulator is started.
Keyboard mapping file syntax
This section describes the syntax of the keyboard mapping file. A statement must
be provided for each key that is needed, because there are no default assignments
(except for the alphabetic and numeric keys). There is no case sensitivity. Each
binding must be on a separate line, and of the following form:
BIND 3270function [modifier+] key [;comment|#comment]
For example, to map the 3270 function EraseEof to the Ctrl+Delete keys pressed
together the binding is as follows:
bind EraseEof Ctrl+Delete ;erase to end of field
The keyboard mapping file
In the mapping file, 3270function can be any one of the following:
backspace pa1 pf1 pf13
backtab pa2 pf2 pf14
clear pa3 pf3 pf15
cursordown pf4 pf16
cursorleft printscreen pf5 pf17
cursorright reset pf6 pf18
cursorselect tab pf7 pf19
cursorup pf8 pf20
delete ignore pf9 pf21
enter pf10 pf22
eraseeof pf11 pf23
eraseinput pf12 pf24
home
insert
newline
Ctrl
Shift
The value of ignore is provided to permit unwanted control keys on the keyboard
to be ignored. (Unexpected glyphs are not generated.)
The Modifier can be either:
The Key can be any one of the keys shown in Table 5, (but some combinations of
modifier+key are not supported — see “Key combinations” on page 91):
Table 5. Keys that you can map
Group Keys
Escape key Escape
Function keys f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 f11 f12
Numeric keys 0 1 2 3 4 5 6 7 8 9
90 CICS Transaction Gateway: UNIX and Linux Administration

Table 5. Keys that you can map (continued)
Group Keys
Alphabetic keys a b c d e f g h i j k l m
n o p q r s t u v w x y z
Tab key Tab
Movement keys newline backspace
insert home pageup
delete end pagedown
up left down right
Keypad keys keypad/ keypad* keypad-
keypad7 keypad8 keypad9
keypad4 keypad5 keypad6 keypad+
keypad1 keypad2 keypad3
keypad0 keypad. keypadenter
Note: For the Client daemon, the Ctrl/Act, Print Screen, Scroll Lock and Pause
keys are not available. The 3270 function Clear is assigned to the Esc key by
default.
Key combinations
The following combinations of modifier and key can be mapped:
No modifier
All keys available for mapping.
Ctrl modifier
Only function keys, movement keys, alphabetic keys, tab key, and keypad
keys can be mapped.
Shift modifier
Only function keys, numeric keys, tab key, and alphabetic keys can be
mapped.
Customizing the screen colors for cicsterm
Screen colors and attributes are defined in a color mapping file. A sample is
provided for you to tailor; see “Sample configuration and mapping files” on page
89 for details. It is recommended that you create your own customized mapping
file.
The color mapping file can be identified by either of these methods:
v The -c option of the cicsterm command, which identifies a color mapping file
with a particular server (see “Customizing the screen colors for cicsterm”).
v The CICSCOL environment variable: For example:
export CICSCOL=/var/cicscli/mycols.ini
If you do not specify otherwise, a file name of cicscol.ini in the /bin
subdirectory is assumed.
A color mapping file provides alternative representations in hardware
environments where it is not possible exactly to replicate 3270 screen attributes, for
example, blinking or underscore. The color mapping file therefore defines how
3270 screen attributes are emulated on the client hardware.
Chapter 5. Configuration 91

If the color mapping file specifies a mapping for an attribute, this mapping is used
even if the hardware upon which the CICS Transaction Gateway is running
actually supports the screen attribute.
If an application requests a 3270 field to be displayed with, for example,
underscore, and no emulation setting has been specified, and the hardware cannot
display underscore, the field is displayed without any highlighting at all.
The color mapping file is optional. However, for most hardware environments a
mapping file is required if blinking or underscore support is required by the
emulator.
You can change the color mapping file at any time, although changes do not take
effect until the next time the terminal emulator is started.
Color mapping syntax
The syntax of the color mapping file is as follows. Each binding must be on a
separate line, in this form:
BIND 3270attrib fg_color [/bg_color] [;comment|#comment]
The file is not case-sensitive.
The color mapping file
In the color mapping file, 3270attrib can be any one of the following:
normal_protected intensified_protected
normal_unprotected intensified_unprotected
default blinking_default underscored_default
blue blinking_blue underscored_blue
green blinking_green underscored_green
cyan blinking_cyan underscored_cyan
red blinking_red underscored_red
magenta blinking_magenta underscored_magenta
white blinking_white underscored_white
yellow blinking_yellow underscored_yellow
default_highlight
operator_information_area
black light_gray
blue light_blue
brown yellow
cyan light_cyan
green light_green
magenta light_magenta
red light_red
gray white
Each of fg_color and bg_color (foreground color and background color) can be any
one of the following:
If bg_color is omitted, a default value of black is taken.
92 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
Preparing to use local CICS Transaction Gateway support
Before you can run an application that uses the local CICS Transaction Gateway
support, ensure that you have a correctly configured environment where CICS
Transaction Gateway binaries can be found.
v The CICS Transaction Gateway .class files need to be available. Set your
CLASSPATH environment variable to include the CICS Transaction Gateway’s
ctgserver.jar and ctgclient.jar archives.
v On Linux and Solaris, set your LD_LIBRARY_PATH environment variable to
include the /bin subdirectory so that your application can find
libctgjni.so.
v On HP-UX set your SHLIB_PATH environment variable to include the
/bin subdirectory so that your application can find libctgjni.sl.
v On AIX, use a shell command like the following to add the /bin
subdirectory to your LIBPATH:
export LIBPATH=/bin:${LIBPATH}
This is so that your application can find file libctgjni.so.
To run the application: use the JDK java command with suitable options. On
platforms other than HP-UX and Solaris: Add the following parameter as an
argument to the Java process:
-Xjni:arrayCacheMax=32768
Checking your configuration
This increases the initial size of the array cache for JNI calls, and is required for
improved performance.
After you have configured your system, check that it is configured correctly.
1. Start the CICS Transaction Gateway.
2. Run one of the sample programs supplied. See file samples.txt, in the
/bin subdirectory, for details, including compilation instructions
and information on compiler considerations.
Related information
“Starting the CICS Transaction Gateway” on page 121
Chapter 5. Configuration 93

94 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 6. Network Security
This information describes how to set up CICS Transaction Gateway to use the
network security protocol SSL.
Java Secure Socket Extension (JSSE)
JSSE is the only supported implementation of the SSL protocol. If a previous
version of the CICS Transaction Gateway was configured to use SSLight or
SystemSSL, you must take steps to migrate the associated resources to a JSSE
configuration. Resources required by for JSSE are certificates stored in either a
KeyStore file (.jks) or RACF ® .
Migrating to JSSE
JSSE is provided as part of the Java Runtime Environment. To avoid possible
conflicts between the different versions of iKeyMan used in SSLight and JSSE, you
are recommended to perform all migration actions before you move to JSSE.
The general process for migrating to JSSE is as follows:
v Create new key ring files and use them instead of existing key rings.
v Change existing security exits that implement the SSLightServerSecurity
interface to implement the JSSEServerSecurity interface.
v Change existing security exits that implement the SystemSSLServerSecurity
interface to implement the JSSEServerSecurity interface.
Migrating keys and certificates
When you are creating a new JSSE application or migrating from another SSL
utility to JSSE, one of the first things to consider is the keys and certificates that
will be used in the application. Do you already have keys and certificates stored
outside a Java KeyStore, in SSLight classes, for example? If so, you need to decide
whether to migrate them to make them available to JSSE and other Java
components and applications.
If you must migrate your keys and certificates from an existing provider, here are
some guidelines for two different conditions:
v “Migrating certificates without private keys”
v “Migrating certificates with private keys” on page 96
Migrating certificates without private keys
A certificate authority or CA certificate does not contain a private key. The two
most common ways to move a CA certificate are Base64 ASCII and DER encoding
formats. You can export Base64 ASCII and DER encoded certificates from most
local databases, such as SSLight classes, to a file. Then you import them into a Java
KeyStore. (You can also export these certificates from a Java KeyStore and import
them into another database, if necessary, for other applications.)
The following steps show how to export a certificate from SSLight to an existing
JSSE keystore (.JKS file) using the iKeyMan utility:
1. From the menu select Key Database File -> Open
© Copyright IBM Corp. 1996, 2006 95

2. Select the Key database type, File Name and Location for the certificate store
to be converted.
3. Enter the key database password when prompted.
4. Select the certificate you want to export.
5. Click Export/Import.
6. Select Export Key as the action type.
7. Ensure JKS is selected as the certificate format.
8. Complete the File Name and Location fields to point to the existing JKS file.
9. Click Yes when asked if you want to update the existing file.
10. Enter the password to open the database into which you are importing the
certificate.
The status bar tells you that the certificate has been exported.
Migrating certificates with private keys
In addition to migrating a CA certificate, you might also need to migrate an end
user certificate — a certificate with a private key — to a JSSE KeyStore. A common
and secure standard used to move end user certificates from one place to another
is the PKCS#12 format. For the example keytool command in Figure 14, export
your certificates using ASCII Base64 encoding. PKCS#12 certificate files are
supported by SystemSSL, SSLight, JSSE, RACF, and other environments. Be aware
that PKCS#12 files can be encoded using different versions of the specification, and
these versions might not always be compatible.
The steps to export a certificate and key to a PKCS#12 file using iKeyMan are
similar to those at “Migrating certificates without private keys” on page 95. After a
PKCS#12 file has been obtained, Figure 14 shows how to import the certificate to a
Java KeyStore.
Figure 14. Importing a certificate and private key from a PKCS#12 file to a Java KeyStore
keytool -import -pkcs12 -file file -alias name -keypass password -storetype jks
-storepass password -keystore keystore -rfc
Maintaining your digital certificates for JSSE
For certificate management you can use the graphical iKeyMan tool, or the
command line keytool, which is included with the SDK. iKeyMan is available only
with IBM SDKs; keytool is available with all SDKs.
You can use these tools to:
v Request and receive a digital certificate from a Certificate Authority (CA).
v Generate self-signed certificates.
v Add certificates to your key ring files.
v Change your key ring password.
v Set a private key as the default.
v Delete a key.
v Export a key by copying it to a file.
v Import a key from an exported copy and add it to a key ring.
To run the iKeyMan tool:
Run the ikeyman command in the bin directory of your Java Runtime
Environment.
96 CICS Transaction Gateway: UNIX and Linux Administration

To run the keytool tool:
From the command line, issue keytool with the parameters required to
perform the task.
Related information
“Using keytool for certificate management” on page 100
Using iKeyMan to manage self-signed certificates under JSSE
JSSE provides a way for you to “self-sign” your certificates. You establish yourself
as your own certificate authority and generate the X.509 digital certificates for the
server (CICS Transaction Gateway) and client (browser) side. The following
sections describe how to configure an SSL server and SSL clients using iKeyMan.
Configuring your SSL server and clients involves:
1. Creating key rings
2. Creating digital certificates
3. Exporting and importing the certificates
Related information
“Using keytool for certificate management” on page 100
Configuring your SSL server
This section describes the configuration process using the iKeyMan tool, for a
command line equivalent see “Configuring your SSL server” on page 101.
1. Create a server key ring
The server key ring contains your Server Certificate, with its associated
private-key, and a number of signer certificates. The Server Certificate is a
digital certificate that SSL uses to identify the server to connecting clients.
a. Start iKeyMan.
b. Select Key Database File —> New.
c. From Key Database Type, select JKS.
d. In File name type a name for your key ring, such as MyServerkey ring.jks.
e. In Location, type a suitable location to store your server key ring.
f. Select OK.
g. Type a password for the key ring file.
iKeyMan gives you an indication of the “strength” of your password. IBM
recommends that you use a mixture of letters and numbers for your
password; this makes the password more resistant to “brute force”
dictionary attacks.
h. Select OK.
The generated file MyServerkey ring.jks contains, by default, a selection of
popular signer certificates as follows:
VeriSign Class 3 Public Primary Certificate Authority
VeriSign Class 2 Public Primary Certificate Authority
VeriSign Class 1 Public Primary Certificate Authority
RSA Secure Server Certificate Authority
Thawte Personal Basic CA
VeriSign Test CA Root Certificate
Thawte Personal Premium CA
Thawte Premium Server CA
Thawte Server CA
Thawte Personal Freemail CA
Chapter 6. Network Security 97

The VeriSign Class 1 through 3 Public Primary Certificate Authority signer
certificates enable the server to verify clients with VeriSign Client Certificates.
2. Create a Server Certificate
Now you are ready to create the self-signed Server Certificate and store it along
with its private key in your server key ring:
a. In iKeyMan, select Personal Certificates from the pull-down menu below
the Key database content label.
b. Select New Self-Signed...
c. Complete the certificate request. Some fields are optional, but you must fill
in at least the following (examples are shown):
Key Label
exampleServerCert
Version
select X509 V3
Key Size
select 1024
Common Name
This defaults to the name of the machine you are using
Organization
The name of your organization
Country
Select a two character ID from the list
Validity Period
The default is 365 days
d. Select OK.
iKeyMan generates a public/private key pair.
e. The self-signed Server Certificate appears in the Personal Certificates
window. The certificate has the name you typed in the Key Label field, in
this example exampleServerCert.
f. With exampleServerCert highlighted, select View/Edit.
Notice that the information in the issued to (certificate requester) textbox is
the same as that in the issued by (signer) textbox. To establish SSL
connections with a server presenting this certificate, the client must trust the
signer. To do this the client key repository must contain the signer certificate
of the server presenting exampleServerCert.
3. Export the server’s signer certificate
a. With exampleServerCert highlighted, select Extract Certificate...
b. In the Data type pull-down menu, select Base64-encoded ASCII.
c. Type the name and location of the text file containing your Server
Certificate data. Our example uses exampleServercert.arm
d. Select OK.
Store the exported certificate in a safe place. Import it into any client repository
that needs to communicate with this SSL server.
Configuring your SSL clients
This section describes the configuration process using the iKeyMan tool, for a
command line equivalent see “Configuring your SSL clients” on page 103.
1. Create a client key ring
98 CICS Transaction Gateway: UNIX and Linux Administration

A client key ring contains as a minimum, the signer certificate of the SSL server,
and a client x.509 certificate, if client authentication is required. The process for
creating a client key ring is similar to that for a server:
a. Start iKeyMan
b. Select Key Database File —> New
c. From Key Database Type, select JKS
d. In File name type a name for your key ring, such as MyClientkey ring.jks
e. In Location, type a suitable location to store your client key ring
f. Select OK
g. Type a password for the key ring file.
h. Select OK
Like the server key ring, the client key ring contains a default selection of
popular signer certificates.
2. Import the server’s signer certificate
a. In iKeyMan select Add
b. Locate the stored Server Base64-encoded ASCII certificate file. In our
example, this is exampleServercert.arm.
c. Select OK.
d. Give this signer certificate a unique label, for example, My Self-Signed Server
Authority.
e. Select OK.
This new signer certificate is added to the list of default signers.
3. Create a Client Certificate
Note: If the SSL handler used by the CICS Transaction Gateway is configured
to support only server authentication, skip step 3 because the client key
ring needs to contain only the signer certificate of the Server, which you
have just imported. You can use the generated MyClientkey ring.jks file
with CICS Transaction Gateway’s SSL protocol, which is configured to
support server authentication.
Client authentication requires the client key ring also to contain a self-signed
Certificate that is used to identify the connecting client.
a. In iKeyMan, select Personal Certificates from the pull-down menu below
the Key database content label.
b. Select New Self-Signed...
c. Complete the certificate request. Some fields are optional, but you must fill
in at least the following (examples are shown):
Key Label
exampleClientCert
Version
Select X509 V3
Key Size
Select 1024
Common Name
This defaults to the name of the machine you are using
Organization
The name of your organization
Chapter 6. Network Security 99

Country
Select a two character ID from the list
Validity Period
The default is 365 days
d. Select OK.
iKeyMan generates a public/private key pair.
e. The self-signed Client Certificate appears in the Personal Certificates
window. The certificate has the name you typed in the Key Label field, in
this example exampleClientCert.
4. Export the client’s signer certificate
a. With exampleClientCert highlighted, select Extract Certificate...
b. In the Data type pull-down, select Base64-encoded ASCII
c. Type the name and location of the text file containing your Server
Certificate data. Our example uses exampleClientcert.arm
d. Select OK.
Store the exported certificate in a safe place. It must be imported into any
server repository that needs to communicate with this SSL client.
Migrating old self-signed certificates (Solaris and AIX operating
systems only)
CICS Transaction Gateway Version 3.0 supported only self-signed certificates, and
not externally signed certificates. You can use your old self-signed certificates by
importing the key ring files, created with Version 3.0, using the iKeyMan tool.
Restricting access to the server key ring
The contents of the server key ring are encrypted and protected by a password.
However you should observe the following points:
v Ensure that the key ring files have appropriate security access permissions
v Restrict access, where applicable, to the CICS Transaction Gateway machine
v Do not share certificates among servers.
v Do not allow servers to share a private key, particularly if they are running on
different machines.
v Never send a private key to someone else.
Using externally signed certificates under JSSE
CICS Transaction Gateway can act as an SSL server, with the ability to authenticate
SSL clients and accept externally signed certificates from Certification Authorities
(CAs) such as VeriSign. Configuring an SSL server and SSL clients using iKeyMan
for use with externally signed certificates is similar to the process for self-signed
certificates. This is described in “Using iKeyMan to manage self-signed certificates
under JSSE” on page 97.
Using keytool for certificate management
The keytool application, provided with the SDK, is an accessible alternative to
iKeyMan. This information describes using the keytool command line application
to manage self-signed certificates. In the production environment you might choose
to use externally signed certificates, which are managed in a similar way.
100 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
Using keytool to manage self-signed certificates under JSSE
Configuring your SSL server:
1. Create a server key ring and create a server certificate.
Issue the following command to create both the KeyStore and certificate:
keytool -genkey -alias aliasname -keysize numericvalue -dname distname
-keystore location -keypass password -storepass password
-keyalg algorithm
The options are:
-genkey
Generates a key pair and wraps the public key into a self-signed
certificate.
-alias aliasname
Defines the alias name that identifies the store containing the
self-signed certificate and private key.
-keysize numericvalue
Defines the size of the key.
-dname distname
Specifies the X.500 distinguished name to be associated with the alias.
This is used as the issuer and subject fields of the self-signed certificate.
The distinguished name consists of a number of fields separated by
commas in the following format:
"cn=strvalue1,o=strvalue2,ou=strvalue3,
l=strvalue4,s=strvalue5,c=strvalue6"
Each strvalue is a string value. The meaning of the abbreviations is as
follows:
v cn = common name
v o = organization
v ou = organization unit
v l = city/locality
v s = state/province
v c = country name
Figure 15 shows an example of an X.500 distinguished name.
"cn=someserver.hursley.ibm.com,o=IBM,ou=IBMGB,
l=Winchester,s=Hants,c=GB"
Figure 15. An X.500 distinguished name
-keystore location
The key ring file location. For example: ktserverss.jks
-keypass password
The password used to protect the private key. Set this to the same value
as the -storepass password, to enable the CICS TG to establish a
connection over SSL.
-storepass password
The password used to protect the integrity of the key ring. Set this to
the same value as the -keypass password, to enable the CICS TG to
establish a connection over SSL.
Chapter 6. Network Security 101

-keyalg algorithm
The algorithm to be used to generate the key pair.
Figure 16 shows an example of this command:
keytool -genkey -alias exampleServerCert -keysize 1024
-dname "cn=vmware2.hursley.ibm.com,o=IBM,ou=IBMGB,l=Winchester,s=Hants,c=GB"
-keystore ktserverss.jks -keypass default -storepass default
-keyalg RSA
Figure 16. Using the keytool command to create a key ring containing a single self-signed certificate
2. View the newly created certificate
If desired, issue a command like the following to view all certificates in the key
ring, including the one you just created:
keytool -list -keystore storename -storepass password -v
Where the options are:
-list List the contents of the key ring.
-keystore storename
The name of the key ring containing the certificates you want to view.
-storepass password
The password needed to access the key ring.
-v Show details of the certificates in the key ring.
Figure 17 shows an example of the keytool command to view certificates:
keytool -list -keystore ktserverss.jks -storepass default -v
Figure 17. Using the keytool command to view certificates
3. Export the server’s signer certificate
The next step is to export the signer certificate and store it in a safe place. This
can then be imported into the repository of any client that needs to connect to
this SSL server. The certificate is exported by using the following instance of
the keytool command:
keytool -export -alias aliasname -keystore location
-storepass password -file filename -rfc
Where the options are:
-export
Export a certificate.
-alias aliasname
Name of the key (in the key ring) to export.
-keystore location
The key ring location.
-storepass password
The password used to protect the integrity of the key ring.
-file filename
The name of the file to export the certificate to.
-rfc Export the certificate in RFC format (Base64 encoded ASCII).
102 CICS Transaction Gateway: UNIX and Linux Administration

Figure 18 shows an example of the keytool command to export a signer
certificate.
keytool -export -alias exampleServerCert -keystore ktserverss.jks -storepass default
-file exampleServerCertKT.arm -rfc
Figure 18. Using the keytool command to export the signer certificate
4. Transfer the server certificate to the client
If you use FTP to transfer the file, ensure that your FTP client is in binary
mode.
Configuring your SSL clients: If your server does not use client authentication
complete only step Create a client key ring and import the server’s signer
certificate. Otherwise complete all steps.
1. Create a client key ring and import the server’s signer certificate.
Issuing the following command to create the key ring and import the
certificate:
keytool -import -alias aliasname -file certfile -keystore keystorefile
-storepass password -noprompt
Where the options are:
-import
Import a certificate.
-alias aliasname
The name under which the certificate is to be stored.
-file certfile
The file that contains the certificate.
-keystore keystorefile
The key ring into which the certificate is to be imported.
-storepass password
The password used to protect the integrity of the key ring.
-noprompt
Removes the need to confirm that the certificate should be imported.
Figure 19 shows an example of this command:
keytool -import -alias exampleServer -file exampleServerCertKT.arm -keystore clientStore.jks
-storepass default -noprompt
Figure 19. Using the keytool command to create a key ring containing the server’s signer certificate
2. Create a self-signed certificate in the client key ring
To create a new keystore containing a self-signed certificate use the following
instance of the keytool command:
keytool -genkey -alias aliasname -keysize numericvalue -dname distname
-keystore location -keypass password -storepass password
-keyalg algorithm
The options are:
-genkey
Generates a key pair and wraps the public key into a self-signed
certificate.
Chapter 6. Network Security 103

|
|
|
|
|
|
|
|
-alias aliasname
Defines the alias name that identifies the store containing the
self-signed certificate and private key.
-keysize numericvalue
Defines the size of the key.
-dname distname
Specifies the X.500 distinguished name to be associated with the alias.
This is used as the issuer and subject fields of the self-signed certificate.
The distinguished name consists of a number of fields separated by
commas in the following format:
"cn=strvalue1,o=strvalue2,ou=strvalue3,
l=strvalue4,s=strvalue5,c=strvalue6"
Each strvalue is a string value. The meaning of the abbreviations is as
follows:
v cn = common name
v o = organization
v ou = organization unit
v l = city/locality
v s = state/province
v c = country name
Figure 20 shows an example of an X.500 distinguished name.
"cn=someserver.hursley.ibm.com,o=IBM,ou=IBMGB,
l=Winchester,s=Hants,c=GB"
Figure 20. An X.500 distinguished name
-keystore location
The key ring file location. For example: ktserverss.jks
-keypass password
The password used to protect the private key. Set this to the same value
as the -storepass password, to enable the CICS TG to establish a
connection over SSL.
-storepass password
The password used to protect the integrity of the key ring. Set this to
the same value as the -keypass password, to enable the CICS TG to
establish a connection over SSL.
-keyalg algorithm
The algorithm to be used to generate the key pair.
An example of this command is shown in Figure 21:
keytool -genkey -alias exampleClientCert -keysize 1024
-dname "cn=John Doe,o=IBM,ou=IBMGB,l=Winchester,s=Hants,c=GB"
-keystore clientStore.jks -keypass default -storepass default
-keyalg RSA
Figure 21. Using the keytool command to create a key ring containing a single self-signed certificate
3. Export the client’s signer certificate
This certificate must be imported into the keystores of all servers that the SSL
client needs to connect to. To export the certificate use the following instance of
the keytool command:
104 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Transport Layer Security
keytool -export -alias aliasname -keystore location
-storepass password -file filename -rfc
Where the options are:
-export
Export a certificate.
-alias aliasname
Name of the key (in the key ring) to export.
-keystore location
The key ring location.
-storepass password
The password used to protect the integrity of the key ring.
-file filename
The name of the file to export the certificate to.
-rfc Export the certificate in RFC format (Base64 encoded ASCII).
Figure 22 shows an example instance of the keytool command to export a
signer certificate.
keytool -export -alias exampleClientCert -keystore clientStore.jks -storepass default
-file exampleClientCertKT.arm -rfc
Figure 22. Using the keytool command to export the signer certificate
4. Transfer the server certificate to the client
If you use FTP to transfer the file, ensure that your FTP client is in binary
mode. For details on importing the certificate, see step Create a client key ring
and import the server’s signer certificate.
5. Import the client signer certificate into the server’s key ring file
The CICS Transaction Gateway supports the Transport Layer Security (TLS)
protocol.
Secure connections between a Java client and the CICS Transaction Gateway and
supported through JSSE, which provides support for two network security
protocols:
v Secure Sockets Layer (SSL) 3.0 protocol.
v Transport Layer Security (TLS) 1.0 protocol. This is the latest industry-standard
SSL protocol and is based on SSL 3.0. The TLS 1.0 specification is documented in
RFC2246 and is available on the Internet at www.rfc-editor.org/rfcsearch.html.
Within this documentation, all references to SSL should be understood as including
TLS. No special configuration or migration steps are required to use TLS.
Information on configuring the CICS Transaction Gateway to use secure protocols
is provided in Chapter 6, “Network Security,” on page 95.
Any connections that require encryption automatically use the TLS protocol, unless
the client specifically requests SSL 3.0 or 2.0.
Chapter 6. Network Security 105

Configuring CICS Transaction Gateway for SSL
You enable the SSL protocol through the Configuration Tool; see “Configuring
Gateway daemon settings” on page 53. When you enable the protocol, by default,
CICS Transaction Gateway listens for SSL requests on port 8050.
If you are using J2EE, consider giving the permissions described in the ″Using a
Java 2 Security Manager″ section of the CICS Transaction Gateway: Programming
Guide:
v If your J2EE application server requires Java 2 Security permissions
v Or if you have enabled Java 2 Security permissions on your server
This will allow the CICS Transaction Gateway to access your Key Stores.
SSL configuration settings
The following configuration settings are specific to the SSL protocol:
“Key ring file” on page 63
Specifies the name of the server key ring.
“Key ring password” on page 64
Specifies the password used to read the encrypted server key ring.
CICS Transaction Gateway writes the password to the configuration file in
a form that prevents a casual observer from easily reading it.
“Use client authentication” on page 63
Enables client authentication. The default is that only server authentication
is enabled.
Using the SSL protocol
You use the SSL protocol in a similar way to the TCP protocol. To make a
connection to CICS Transaction Gateway, your client application flows a request
using the appropriate URL. For example, use a URL like:
ssl://transGatewayMachine:8050
For more information on the design and implementation of client-side programs,
see the CICS Transaction Gateway: Programming Guide, and the CICS Transaction
Gateway programming interface HTML pages.
106 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 7. Client security
Client security overview
Default connection settings
This information describes how to provide a user ID and password when
connecting to a CICS server.
CICS servers might require the Client daemon to supply a user ID and password
before they permit the following:
v A client connection
v Terminals to be installed
v Transactions to be run
This depends on the server and protocol security settings. The user ID and
password are sent to the server of the transaction attach request for each
conversation. A user ID and password are also required when a sign-on transaction
is invoked on a sign-on capable terminal. In this instance, the user ID and
password are flowed to the server as part of the 3270 data stream.
User IDs and passwords must not contain DBCS characters.
If no user ID is passed by a CICS Transaction Gateway user application, and no
default is set by the CICS Transaction Gateway, the transaction is run using the
mainframe CICS server’s default user ID and password if the Usedfltuser
parameter on the CICS server connection definition is set to Yes. If this parameter
is set to No, security is enforced by the host CICS server and a user ID and
password will need to be supplied. In each case, transactions execute in the server
with the authorities assigned to the user ID authenticated.
Because the Client daemon has no security manager, it does not support user ID
authentication. Configure your CICS server client connections so that incoming
attach requests must specify a user ID and password. For mainframe servers,
specify AttachSec = Verify in the CICS connection definition. AttachSec =
Identify, which indicates that a user ID, but not password, is required, is not
supported for client connections.
The Client daemon maintains a default user ID and password for each server
connection, which can be set by any of the following methods:
v CICSCLI security commands:
cicscli -c=servername -u=userid -p=password
The servername parameter can also be specified with the -s option.
v From C use the ESI function CICS_SetDefaultSecurity. This call is not available
from the Java APIs.
v From C++, use the makeSecurityDefault method of the CclConn or
CclTerminal class.
These default values are used when required on all subsequent transaction requests
for that server, provided that no values have been passed on the ECI request itself,
or have been set for the specific EPI terminal against which the transaction will
run.
© Copyright IBM Corp. 1996, 2006 107

ECI security
EPI terminal security
Note: If the Client daemon is running in an environment where it survives user
logoff, the default user ID and password values entered by the current user
are retained even when that user logs off, and are subsequently reused as
required.
An application can provide a user ID and password on an ECI request; these
values override any default values set for the server connection.
C programs
Set eci_userid and eci_password or eci_userid2 and eci_password2 in the ECI
parameter block.
C++ programs
Set the userid and password parameters when constructing a server connection
object - CclConn.
COM programs
Set the userid and password via the Details method on the Connect object.
Java Client applications
Set the userid and password parameters when constructing an ECIRequest
object.
The Client daemon also maintains a user ID and password for each installed
terminal. These values override any default values set for the server connection. .
Terminal security is normally required only if using sign-on incapable terminals.
Changing the user ID and password
The user ID and password may be changed at any time, as follows:
v C programs:
Set UserId and Password in the CICS_EpiAttributes_t structure on a
CICS_EpiAddExTerminal call. Or, use the EPI function CICS_EpiSetSecurity.
This call would typically be used to change the terminal security settings if, for
example, the user’s password had expired.
v C++ programs:
Set the userid and password parameters when constructing a CclTerminal class
object. Or, use the alterSecurity method of the CclTerminal class.
v Java Client applications:
– EPI Request Classes
Set the userid and password parameters when constructing an EPIRequest
object via the addTerminal or addTerminalAsync method. Or, use the
alterSecurity method of the EPIRequest class.
– EPI Support Classes
Create a Terminal object using the default Constructor, then use setUserid
and setPassword to set security, or create a Terminal object using the
extended Constructor.
108 CICS Transaction Gateway: UNIX and Linux Administration

Password expiry management
For CICS clients, the management of expired passwords can be handled by the ESI
functions CICS_ChangePassword and CICS_VerifyPassword.
The ESI functions can be used only with CICS servers that support password
expiry management (PEM). See “Supported software” on page 19 for information
on supported servers. Refer to the documentation for your CICS server for
information on PEM support.
To use PEM, the Client daemon must be connected to the CICS server over TCP62
or SNA. An External Security Manager such as Resource Access Control Facility
(RACF), must also be available to the CICS server. ESI calls can be included within
your ECI or EPI application. Only CICS servers returned by the
CICS_EciListSystems and CICS_EpiListSystems functions are valid.
Sign-on capable and sign-on incapable terminals
Sign-on capable terminals allow sign-on transactions, either CICS-supplied (CESN)
or user-written, to be run, whereas sign-on incapable terminals do not allow these
transactions to be run.
If a terminal resource is installed as sign-on capable, the application or user is
responsible for starting a sign-on transaction; the user ID and password, once
entered, are embedded in the 3270 data. If the terminal resource is installed as
sign-on incapable, the user ID and password are authenticated for each
transaction started for the terminal resource.
Specifying the sign-on capability of a terminal
Prior to Version 3.1.0 of Clients and Gateways, whether a terminal was sign-on
capable or not depended upon the server implementation. Client terminals
installed on distributed CICS servers were sign-on capable; terminals installed on
mainframe CICS and CICS Transaction Server for iSeries servers were sign-on
incapable.
In Version 3.1.0, extended EPI function was introduced to allow the sign-on
capability of a terminal to be specified by one of the following methods.
v C programs:
Use CICS_EpiAddExTerminal and set the sign-on capability parameter in the
CICS_EpiAttributes_t structure.
v C++ programs:
Set the sign-on capability parameter when constructing a CclTerminal class
object.
v Java Client applications:
– EPI Request Classes
Set the sign-on capability parameter when constructing an EPIRequest object
via the addTerminal or addTerminalAsync method.
– EPI Support Classes
Create a Terminal object using the default Constructor, then use
setSignonCapability, or create a Terminal object using the extended
Constructor. If a terminal is in disconnected state (ie has been disconnected,
or never connected) calling setSignonCapability allows you to change the
sign-on capability for the terminal and changes the terminal type to extended.
Chapter 7. Client security 109

When you connect, you connect an extended terminal with that sign-on
capability. Setting the sign-on capability while a terminal is connected does
not alter the connected setting; the setting is stored.
The sign-on capability of the installed terminal is returned in the terminal
attributes. This will be set to SIGNON_UNKNOWN if the server does not return a
sign-on capability parameter in the terminal install (CTIN) response.
To use any of the extended EPI functionality, ensure that you have applied the
relevant server APAR; see “CICS server PTF requirements” on page 24.
Mainframe CICS servers
These servers support both sign-on capable and incapable terminals, provided that
they are at the prerequisite maintenance level. A terminal install request that does
not specify any sign-on capability, for example from CICS_EpiAddTerminal,
results in a sign-on incapable terminal being installed.
For sign-on capable terminals:
v Use the CICS_EpiAddExTerminal call specifying a SignonCapability of
CICS_EPI_SIGNON_CAPABLE.
v You do not need to set the userid and password fields on the
CICS_EpiAddExTerminal call or use CICS_EpiSetSecurity, provided that you
specify UseDfltUser = Yes in the CICS connection definition on the server.
v A userid and password entered through a sign-on transaction are flowed to the
server as part of the 3270 data stream and they will therefore appear in a client
trace.
Specify UseDfltUser = Yes in the CICS CONNECTION definition, or ensure that
the system administrator sets a default connection userid and password for the
client. Otherwise, the add terminal request might fail with an
EPI_ERR_SECURITY return code. The default user ID must have sufficient
privileges to allow the CTIN transaction to run.
v Before the user has signed on, transactions run under the default userid for the
CICS server. After sign-on, transactions run under the signed-on userid.
For sign-on incapable terminals without terminal security:
v Use the CICS_EpiAddTerminal call
v A connection userid and password are required regardless of the setting of the
UseDfltUser in the CICS connection definition on the server.
v Transactions run under the userid specified in the corresponding FMH attach
request.
For sign-on incapable terminals with terminal security:
v Use the EpiAddExTerminal call specifying a SignonCapability of
CICS_EPI_SIGNON_INCAPABLE.
v Set the userid and password fields on the CICS_EpiAddExTerminal call.
v Specify UseDfltUser = No in the CICS connection definition on the server to
enforce security.
v Use CICS_EpiSetSecurity in conjunction with CICS_VerifyPassword and
CICS_ChangePassword to change the security settings for an existing terminal.
v The userid and password are flowed to the server in the FMH of the attach
request and will not appear in a client trace.
v Transactions will run under the userid specified in the corresponding FMH
attach request.
110 CICS Transaction Gateway: UNIX and Linux Administration

To use one of the APIs that does not support the extended EPI functionality, use
CRTE through a middle tier system to get sign-on capable terminal-like
functionality.
CICS Transaction Server for iSeries servers
These servers do not support the sign-on capability parameter in a terminal install
(CTIN) request. A terminal install request always results in a sign-on incapable
terminal being installed.
Chapter 7. Client security 111

112 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 8. Performance
This information helps you to:
v Understand the factors that affect CICS Transaction Gateway performance
v Achieve the best performance from your system
Related tasks
“Displaying statistics” on page 187
Use ctgadmin to display statistical information about the CICS Transaction
Gateway.
Related reference
Assessing system performance
“List of statistics” on page 189
This information describes the statistics that are available from the CICS
Transaction Gateway.
To assess the overall performance of your system you need to understand how all
system components, including CICS Transaction Gateway, affect performance.
These system components might include:
v Browser
v Routers and firewalls
v Web application server or J2EE application server
v CICS Transaction Gateway
v CICS server
The information you collect to assess performance should include:
v Processor loading
v Data transfer rates
v Response times
Response times are particularly useful indicators. They help you to understand
which system components most affect performance.
The CICS Transaction Gateway threading model
CICS Transaction Gateway provides a multithreaded model for handling network
connections, and for assigning threads for requests from, and replies to, Java Client
applications. The threading model uses the following objects:
ConnectionManagers
Workers
A ConnectionManager manages all the connections from a particular Java
Client application. When it receives a request, it allocates a worker thread
from a pool of available worker threads to execute the request.
A Worker is the object that actually executes a request from a Java Client
application. Each Worker object has its own thread, which is activated
when there is some work to do. When a worker thread has finished
processing it returns to the pool of available worker threads.
© Copyright IBM Corp. 1996, 2006 113

You can set both the initial and maximum sizes of the resource pools for these
objects; see “Configuring Gateway daemon settings” on page 53 for information on
setting configuration parameters. You can also specify these limits when you start
the CICS Transaction Gateway; see “Starting the Gateway daemon with
user-specified options” on page 123.
Table 6 shows thread limits that should be considered when setting the number of
Connection Manager and worker threads on the various operating systems:
Table 6. Thread limits
Operating
system
System-wide limit of
the maximum number
of threads
AIX 262 143 32 768
HP-UX No limit (30 000 kernel
threads)
Linux Equal to the maximum
number of processes
Solaris No limit No limit
Process limit of the number of threads
30 000 (refer to the max_thread_proc parameter
under Configurable Kernel Parameters in the
SAM utility)
1024 (refer to your Linux Threads
documentation for more information)
For more information on the way Java allocates memory for threads, refer to
“Performance issues” in the CICS Transaction Gateway: Programming Guide.
The threading model is illustrated in the following figure:
Figure 23. CICS Transaction Gateway threading model for TCP/IP and SSL. These protocols have a persistent socket.
Related tasks
“Displaying statistics” on page 187
Use ctgadmin to display statistical information about the CICS Transaction
Gateway.
Related reference
114 CICS Transaction Gateway: UNIX and Linux Administration

“List of statistics” on page 189
This information describes the statistics that are available from the CICS
Transaction Gateway.
Tuning your configuration parameters
The default values that have been chosen for configuration and tuning aim to give
a compromise between:
v Limiting the system resources used by CICS Transaction Gateway after it has
started
v Giving the CICS Transaction Gateway the flexibility to handle increases in
workload
The following factors affect performance; you might need to alter the default
configuration to suit your system environment:
Connection Manager threads
v If the value specified for Initial number of Connection Manager
threads is too high, your system will waste resources managing the
threads that are not needed. See “Initial number of Connection Manager
threads” on page 53 for more information.
v If the value for Maximum number of Connection Manager threads is
too low to meet all requests from applications, each new request that
requires a Connection Manager thread must wait for a thread to become
available. If the waiting time exceeds the value specified in the
Connection timeout parameter, the CICS Transaction Gateway refuses
the connection. See “Maximum number of Connection Manager threads”
on page 54 for more information.
The design of your applications determines the number of Connection
Manager threads you need. Incoming connections to CICS Transaction
Gateway could be from a servlet, with each copy of the servlet issuing its
own ECI requests, but sharing a single Connection Manager thread.
Alternatively, the application could create a pool of connections, and ECI
requests could be issued onto any connection from the pool.
CICS Transaction Gateway creates a new Connection Manager thread, and
TCP/IP connection, each time a Java client side application creates a new
JavaGateway object. This means that system performance is better if your
applications issue many ECI requests using the same JavaGateway object,
and from within the same thread, than if they create a new JavaGateway
object for each request.
Flowing multiple requests through the same JavaGateway object also
reduces the system resources required to create, and to destroy,
JavaGateway objects.
Worker threads
Worker threads handle outbound connections between CICS Transaction
Gateway and your CICS server. The design of your applications, and the
workload that you need to support, affects the number of Worker threads
you need: the longer your CICS transactions remain in process, the more
Worker threads you need to maintain a given transaction rate.
v If the value specified for Initial number of Worker threads is too high,
CICS Transaction Gateway uses resources to manage threads that it does
not need.
Chapter 8. Performance 115

|
Java considerations
v If the value is too low, CICS Transaction Gateway uses resources to
search for available Worker threads.
See “Initial number of Worker threads” on page 54 for more information
about the Initial number of Worker threads setting.
When using ECI to call the same CICS program, you can estimate the
number of Worker threads you need to support a given workload by
multiplying the following values:
v The number of transactions per second passing through CICS
Transaction Gateway
v The average transaction response time through CICS Transaction
Gateway in seconds
Communication protocols
Your choice of protocol depends on the nature of your client applications.
Display TCP/IP hostnames
Selecting this option might cause severe performance reduction on some
systems. See “Display TCP/IP hostnames” on page 57.
Timeout values
It is unlikely that you can improve performance by changing the default
timeout values. However, you might need to change them for particular
applications. Refer to “Configuring Gateway daemon settings” on page 53
for more information on these configuration parameters.
Connection logging
The Gateway configuration setting, Log Java Client connections and
disconnections, controls whether or not CICS Transaction Gateway writes
a message each time that a client application program connects to, or
disconnects from, the Gateway daemon. The default is for these messages
not to be written. Selecting this setting can significantly reduce
performance, especially in a system where client application programs
connect and disconnect frequently. See “Log Java Client connections and
disconnections” on page 58.
Related tasks
“Displaying statistics” on page 187
Use ctgadmin to display statistical information about the CICS Transaction
Gateway.
Related reference
“List of statistics” on page 189
This information describes the statistics that are available from the CICS
Transaction Gateway.
Maximum Java heap size
If your system requires large numbers of Connection Manager threads you
might need to increase the heap size to improve performance; but see
“java.lang.OutOfMemory exception” on page 159 for information on
potential problems if the heap size is too large. How you set the heap size
depends on your JVM. Refer to the documentation for your JVM for more
information.
Just-In-Time (JIT) compiler
Use the java -version command to find whether or not the JIT is enabled; it
116 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
Other system factors
is enabled by default. Immediately after a CICS Transaction Gateway has
started, performance might be relatively slow because of JIT overheads.
Refer to your JVM documentation for information on JIT techniques.
JavaGateway objects
Performance is better if you flow multiple requests using the same
JavaGateway object than if you create a new JavaGateway object with each
request. Each time you create, and destroy, a new JavaGateway object you
use additional system resources for:
v Creation and destruction of the object itself
v Creation and destruction of any associated sockets
v Garbage collection
ECI COMMAREA size
The size of the ECI COMMAREA has a large effect on performance. If you
make the COMMAREA larger, you need more system resources to process
it, and your response times are longer. Refer to CICS Transaction Gateway:
Programming Guide for information on how to specify COMMAREA
parameters in ECI requests.
The setCommareaOutboundLength method, which is part of the
ECIRequest object, is particularly important to performance. The amount
of data that an application sends in the COMMAREA flow to CICS might
be small, and the amount of data expected from CICS in return might be
unknown. To improve performance significantly, and reduce network
loading:
v Use the setCommareaOutboundLength method to ensure that you send
only the required data in the outbound flow to CICS, and not the full
Commarea_Length.
CICS removes any null data from the COMMAREA in the return flow,
and the Client daemon automatically pads out the nulls and returns the
full COMMAREA to the application.
v Use the getInboundDataLength method to show the amount of non-null
data returned.
v You can use either the setCommareaInbound method or null stripping.
Use setCommareaInbound when the size of inbound data is known in
advance. See CICS Transaction Gateway: Programming Guide for more
details about when to use these options.
CICS server transactions
The design of your CICS server transactions affects the performance of
your system. The response time through the CICS Transaction Gateway
might increase if your transactions:
v Need to wait for shared resources, for example data sets or applications,
to become available
v Make remote links to other CICS systems
v Are unnecessarily complex
Refer to the performance and tuning documentation for your CICS server
system for information on how to get the best performance.
Synchronous or asynchronous ECI calls
CICS Transaction Gateway has to do less processing to handle a
synchronous ECI call than to handle an equivalent asynchronous call. Also,
Chapter 8. Performance 117

Tracing and performance
synchronous ECI calls create fewer network flows than asynchronous calls.
This means that synchronous ECI calls give better performance than
asynchronous calls.
Extended logical units of work
Take care when extending a logical unit of work across multiple program
link calls that might span a long time period (for example, user thinking
time). The logical unit of work holds various locks, and other CICS
resources, on the server. This might cause delays to other users who are
waiting for the same locks and resources.
Also, each logical unit of work occupies one CICS non-facility task for the
duration of its execution. This means that you must define enough free
tasks in the CICS server to service the maximum expected number of
concurrent calls.
Refer to CICS Transaction Gateway: Programming Guide for more information.
Tracing the Client or the Gateway daemon reduces performance significantly. Client
trace means all the components of the CICS Transaction Gateway that go to the
Client trace file. Where possible, try to measure response times, without using
tracing, through the different parts of your system, to find where delays are
happening. For example, you could measure response times at the user application,
or through the facilities provided by CICS and WebSphere Application Server.
The Client trace provides a greater level of control than is currently available for
Gateway trace. If you need to trace the Client, take the following steps to lessen
the impact on performance:
v Use memory mapped trace whenever possible; see “Memory mapped tracing”
on page 163. This should be suitable in most cases, unless it was not possible to
flush the buffers, for example.
v Start by specifying the API.2, CCL and DRV.1 components. If this does not
isolate the problem, include extra components as necessary.
IBM does not recommend the use of the full CICS Transaction Gateway trace to
monitor performance in a production environment.
Performance monitoring tools
The following performance monitoring tools are available on the AIX operating
system. Similar tools are available on other UNIX and Linux operating system:
vmstat
Gives statistics about virtual memory, disks, traps, and processor activity.
Use it to determine system loading.
iostat Gives processor statistics and I/O statistics for tty, disks, and CD-ROM
drives.
sar (system activity report)
Collects, reports, or saves system activity information.
netstat
Shows network status.
118 CICS Transaction Gateway: UNIX and Linux Administration

IBM Performance Toolbox
Provides some useful performance tools that are integrated into a graphical
user interface. Versions are available for the Solaris and HP-UX operating
systems.
Refer also to the performance and tuning documentation for WebSphere, SNA,
TCP/IP, CICS Transaction Server for z/OS, and TXSeries, and the documentation
supplied with your operating system.
Chapter 8. Performance 119

120 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 9. Operating the CICS Transaction Gateway
This information discusses how to operate the CICS Transaction Gateway product,
including the Gateway daemon and the Client daemon.
Starting the CICS Transaction Gateway
You do not need to explicitly start the Client daemon. Start the Gateway daemon
by issuing the ctgstart command. The Client daemon starts automatically when
the first request is flowed. See “Starting the Gateway daemon” on page 123 for
information on the ctgstart command.
Stopping the CICS Transaction Gateway
Stop the daemons in this order:
Changing the system time
1. Gateway daemon. See “Stopping the Gateway daemon” on page 125 for details.
2. Client daemon. See “The cicscli command” on page 133 for details.
Shutting down the Client daemon while the Gateway daemon is still running is
not supported. If the Client daemon is shut down while the Gateway daemon is
still running, Client applications fail with ECI_ERR_SYSTEM_ERROR or
CICS_EPI_ERR_FAILED errors, and the Client daemon is not automatically
restarted. The same issue applies if the Client daemon is shut down when a long
running user application is still running. To resolve the situation, shut down and
restart the Gateway daemon.
Do not change the system time while the CICS Transaction Gateway is running.
This can give unpredictable results, and is not supported.
© Copyright IBM Corp. 1996, 2006 121

122 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 10. Operating the Gateway daemon
Starting the Gateway daemon
This information describes how to operate the Gateway daemon of CICS
Transaction Gateway.
This information describes how to start the Gateway daemon.
Starting the Gateway daemon with preset options
To start the Gateway daemon with the options specified in ctg.ini, type ctgstart at
the command prompt and press Enter.
The Gateway daemon will not start without a valid ctg.ini file.
A console session starts, and messages are displayed showing the values being
used for TCP/IP.
Starting the Gateway daemon with user-specified options
To override the startup defaults type ctgstart at the command line, followed by the
start-up options that you require, and press Enter.
The user-definable options on the start command are:
-port=port_number
-initconnect=number
-maxconnect=number
-initworker=number
-maxworker=number
-trace
-quiet
-tfile=pathname
-x
-tfilesize=number
-truncationsize=number
-dnsnames
-dumpoffset=number
-stack
-adminport=number
-jargument
where:
-port=number
Specifies the TCP/IP port number on which the Gateway daemon will listen.
-initconnect=number
Specifies an initial number of ConnectionManager threads. See “Tuning your
configuration parameters” on page 115 for performance information.
-maxconnect=number
Specifies a maximum number of ConnectionManager threads. If you set this
value to -1, no limits are applied to the number of ConnectionManager threads.
See “Tuning your configuration parameters” on page 115 for performance
information.
© Copyright IBM Corp. 1996, 2006 123

-initworker=number
Specifies an initial number of worker threads. See “Tuning your configuration
parameters” on page 115 for performance information.
-maxworker=number
Specifies a maximum number of worker threads. If you set this value to -1, no
limits are applied to the number of ConnectionManager threads. See “Tuning
your configuration parameters” on page 115 for performance information.
-trace
Enables standard tracing (see “Tracing” on page 155). By default, the trace
output shows only the first 128 bytes of any data blocks (for example the
COMMAREA, or network flows). Other useful information, including the
value of the CLASSPATH variable, and the code page, is shown at the top of
the trace output.
Trace output is written to stderr, unless you use the -tfile option, or have used
the Configuration Tool to define a default trace destination. No trace is written
if the Gateway daemon does not have permission to write to the specified file.
Each time the Gateway daemon is started with trace enabled, the trace file is
overwritten with the new trace.
-quiet
Disables the reading of input from the console, and disables writing to stdout.
-tfile=pathname
If tracing is enabled, trace output is written to the file specified in pathname.
This overrides the default destination for trace output (see the -trace option).
-x Enables full debug tracing (see “Tracing” on page 155). By default, the trace
output shows the whole of any data blocks (for example the COMMAREA, or
network flows). It also displays more information about the internal Gateway
daemon processing than the standard trace. See the -trace and -tfile options for
information on the destination for trace output.
Debug tracing significantly decreases performance.
-tfilesize=number
Specifies the maximum size, in kilobytes, of the trace output file.
-truncationsize=number
The value number specifies the maximum size of any data blocks that are
shown in the trace. You can use this option with either the -trace or -x options
to override the default size. Any positive integer is valid. If you specify a value
of 0, no data blocks are shown in the trace.
-dnsnames
Enables the display of symbolic TCP/IP host names in messages. See “Display
TCP/IP hostnames” on page 57 for more information.
-dumpoffset=number
The value number specifies the offset from which displays of any data blocks
start. If the offset is greater than the total length of data to be displayed, an
offset of 0 is used.
-stack
Enables Java exception stack tracing (see “Tracing” on page 155). Java
exceptions are traced, including those expected during normal operation.
Expected exceptions include:
v An IOException resulting from a Java Client application ending, or
disconnecting from a network protocol.
124 CICS Transaction Gateway: UNIX and Linux Administration

v An InterruptedException resulting from a CICS Transaction Gateway
protocol handler timeout, such as the idle timeout, or a ping timeout.
No other trace output is created. See the -trace and -tfile options for
information on the destination for trace output.
-adminport=number
Specify the port used to communicate with the Gateway daemon when
controlling the Gateway daemon through the ctgadmin command.
-j Pass an argument to the JVM. For example, -j-D= sets a JVM
system property. See the JVM command line interpreter help for guidance in
using this option.
A console session starts, and messages are displayed showing the values being
used for TCP/IP.
To get help on the startup options, enter:
ctgstart -?
Stopping the Gateway daemon
There are two types of shutdown: normal and immediate.
Normal shutdown
In a normal shutdown, the Gateway daemon waits for work in progress to
complete. During this time, new work is not allowed to start. Once work
has completed the Gateway daemon shuts down.
Immediate shutdown
Any outstanding work is terminated abruptly. Existing connections are
broken; requests for new connections are refused. The Gateway daemon
shuts down.
You can perform an immediate shutdown if a normal shutdown is taking too long.
You cannot request a normal shutdown after you have issued the command for an
immediate shutdown.
To shut down the Gateway daemon:
v Use the ctgadmin command. The command is described at “Shutting down the
Gateway daemon” on page 127.
v If you did not start the Gateway daemon with the -quiet option, you can stop it
by typing the correct character and pressing the Enter key in the console session.
Accepted characters are as follows:
Normal shutdown
Q or -
Immediate shutdown
I
Using Ctrl+C to stop the Gateway daemon is not supported.
If you have problems stopping the Gateway daemon, see “Problems shutting down
the Gateway daemon” on page 161.
Chapter 10. Operating the Gateway daemon 125

|
|
|
|
|
Running the Gateway daemon in the background
Using a SysV-compliant initialization process script, /bin/ctgd, you
can run the Gateway daemon as a background process. You can:
v Define the user and group that the Gateway daemon will run as.
v Specify the location of ctg.ini.
v Start the Gateway daemon with parameters.
v Start and stop the Gateway daemon when the system starts and stops.
v Specify the TCP port on which the Gateway daemon listens for local
administration requests. The default port is 2810. The ctgd script does not use
the port specified in ctg.ini.
The command takes start and stop parameters, and can be called during the
startup and shutdown processes of your operating system.
To run the Gateway daemon as a background task, take the following steps:
1. Create a valid /bin/ctgd.conf file. The recommended way is to
copy /bin/ctgdsamp.conf and edit the copy. You are advised to
specify the user and group which will run the Gateway daemon. The sample
file contains instructions on how to produce a valid configuration file.
If you need to change the location of ctgd.conf, export environment variable
$CTGDCONF by issuing a command like the following:
export CTGDCONF=/opt/IBM/cicstg/bin/ctgd.conf
2. To start the Gateway daemon as a background process, issue this command:
ctgd start
3. To stop a Gateway daemon that is running as a background process, issue this
command:
ctgd stop
Administering your system
This stops the Gateway daemon immediately.
4. If you want the Gateway daemon to start and stop with the operating system,
place a symbolic link to /bin/ctgd in the appropriate directory,
or edit /etc/inittab. See the documentation supplied with your operating
system for more details.
Administering your system
You can perform the following administrative functions without having to restart
the CICS Transaction Gateway for them to take effect:
v Set the Gateway trace
v Set JNI trace
v Query the current trace settings
v Stop the Gateway daemon
v Display statistical information about the CICS Transaction Gateway.
v Obtain a Java heap dump, a system dump, or a Java dump from a running IBM
JVM.
v Obtain dumps containing information about the CICS Transaction Gateway
configuration, and the current JVM.
126 CICS Transaction Gateway: UNIX and Linux Administration

Use the ctgadmin command, followed by appropriate options, to administer your
system. Options are not case sensitive; those in brackets are optional.
You can run the ctgadmin command from a script, and check the results
programmatically. See CICS Transaction Gateway: Programming Guide for details of
return codes used by the ctgadmin command.
Setting the Gateway trace
At the command line, issue the following command:
ctgadmin -a trace [-tfile path]
[-tfilesize number] [-tlevel number]
[[-truncationsize number][-dumpoffset number]|-fulldatadump]
See “Administration options” for an explanation of options.
Setting the JNI trace
At the command line, issue the following command:
ctgadmin -a trace [-jnifile path] [-jnilevel number]
See “Administration options” for an explanation of options.
Setting Gateway and JNI trace
At the command line, issue the following command:
ctgadmin -a trace [-tfile path]
[-tfilesize number] [-tlevel number]
[[-truncationsize number][-dumpoffset number]|-fulldatadump]
[-jnifile path] [-jnilevel number]
See “Administration options” for an explanation of options.
Querying trace settings
At the command line, issue the following command:
ctgadmin -a trace
See “Administration options” for an explanation of options.
Shutting down the Gateway daemon
At the command line, issue the following command:
ctgadmin -a shut [-immediate]
Getting help
At the command line, issue the following command:
ctgadmin -?
To get help on a particular action, issue a command like the following:
ctgadmin -a action -?
Administration options
The following options are available:
Chapter 10. Operating the Gateway daemon 127

Shutdown options
This option is available for use with the ctgadmin -a shut command.
To get help on these options, issue the following command:
ctgadmin -a shut -?
Option Short form Comments
-immediate -imm Specifies that the Gateway daemon
should shut down immediately. If you
do not specify this option, a normal
shutdown is performed.
Trace options
These options are available for use with the ctgadmin -a trace command.
To get help on these options, issue the following command:
ctgadmin -a trace -?
Option Short form Comments
-dumpoffset -of Specifies the offset from which displays
of any data blocks start, for example
512. If the offset is greater than the
total length of data to be displayed, an
offset of 0 is used. This option applies
only to the Gateway trace, not JNI
trace.
You cannot use this together with the
fulldatadump option.
-fulldatadump -fd Sets the dumpoffset to 0 and ignores
any value specified in truncationsize.
This option applies only to the
Gateway trace, not JNI trace.
-jnifile -jf Specifies the name of the output file for
JNI tracing. You must specify a value
for this option. If you do not, an error
is displayed. JNI trace is output as
plain text, and there is no requirement
to use a particular extension for the file
name.
-jnilevel -jl
0 Off. No trace information is
output.
1 On.
-tfilesize -ts Specifies the maximum size, in
kilobytes, of the Gateway trace output
file, for example 50000.
-tfile -tf Specifies the output file for Gateway
tracing, for example ./tracefile.trc. If
you do not specify a value for this
option, trace output is sent to the
console.
128 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Option Short form Comments
-tlevel -tl Specifies the Gateway trace level.
Permitted values are:
0 Off. No trace information is
output.
1 Exception tracing. Only
exceptions are traced. This is
equivalent to ctgstart -stack;
see “Starting the Gateway
daemon with user-specified
options” on page 123.
2 Trace exceptions, and entry
and exit of methods.
3 Trace exceptions, some
internals, and entry and exit of
methods (equivalent to
ctgstart -trace).
4 Full debug tracing (all trace
points, equivalent to ctgstart
-x).
-truncationsize -tr Specifies the byte at which to stop the
hex dump, for example 2000. It defines
the end point, not the number of bytes
to display. So if on a dump of size 40
you set the dumpoffset to 11, and the
truncationsize to 25, you will see 15
bytes (from 11 to 25).
You cannot use this together with the
fulldatadump option. This option
applies only to the Gateway trace, not
JNI trace.
Statistical options
These options are available for use with the ctgadmin -a stats command.
To get help on these options, issue the following command:
ctgadmin -a stats -?
Option Short form Comments
-getstats -gs Lists all available statistics.
-getstats=query string -gs=query string Lists statistics for the IDs specified in
query string.
-resourcegroups -rg Lists available resource group IDs
-statids -si Lists available statistical IDs
-statids=resource group ID -si=resource group ID Lists available statistical IDs for the
specified resource group, or list of
resource groups.
Related tasks
“Displaying statistics” on page 187
Use ctgadmin to display statistical information about the CICS Transaction
Gateway.
Chapter 10. Operating the Gateway daemon 129

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Dump options
Dump options are available for use with the ctgadmin -a dump command.
To get help on these options, issue the following command:
ctgadmin -a dump -?
Dumps contain diagnostic information that can be used when investigating system
problems.
If the IBM JVM is used, a subset of the options can be used to provide JVM
dumps. The IBM JVM can produce a Java heap dump, a Java dump, or a Java
system dump. These are produced by a running JVM, and can be requested during
normal operation of the CICS Transaction Gateway. The dumps contain diagnostic
information that can be used when investigating system problems.
For further information on IBM JVM dumps, see the IBM Java Diagnostic Guide at
http://www-128.ibm.com/developerworks/java/jdk/diagnosis/.
Dump file location
The dumps write information to a location chosen from the first available option in
the following list:
1. The location specified by the IBM_JAVACOREDIR environment variable, if set.
2. The current working directory of the JVM processes, if permitted.
3. The location specified by the TMPDIR environment variable, if set.
4. The /tmp directory.
5. If the dump cannot be written to any of the previous locations, it is sent to
STDERR.
Parameters
There are no short forms of the parameter names.
Parameter Comments
-jvm Generates a dump containing current JVM memory
usage.
-jvmstack Generates a dump containing only the Java call stack.
-ctginfo Generates a dump containing information about the
configuration of the CICS Transaction Gateway.
-heap (IBM JVM only.) Generates a Java heap dump to the
default location. The dump file has a file name of the
form heapdump.YYYYMMDD.HHMMSS..phd
-java (IBM JVM only.) Generates a Java dump to the default
location. The dump file has a file name of the form
javacore.YYYYMMDD.HHMMSS..phd
-system (IBM JVM only.) Generates a Java system dump to the
default location. The dump file has a file name of the
form core.YYYYMMDD.HHMMSS..phd
130 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Responses
The CICS Transaction Gateway daemon responds to a dump request with a
message to the console.
IBM JVM dump responses
Messages from the JVM contain the name of the dump, and indicate whether the
dump was successful. The JVM messages are sent to the Gateway error log.
Possible responses to the dump request are as follows:
The Gateway daemon successfully processed the dump request
The dump request completed successfully.
Null response received from the Gateway daemon during the dump request
The Gateway daemon received the dump request, but returned an invalid
or null response.
The dump type is unsupported in the remote JVM
The remote JVM does not support the requested dump type.
An invalid response was returned from the Gateway daemon during the dump
request
The Gateway daemon received the dump request, but the response
returned was invalid.
The Gateway daemon encountered a serious error while processing the dump
type The Gateway daemon received the dump request, but an error was
detected.
Other options
This option is available for use with the ctgadmin -a command.
Option Short form Comments
-dbg [filename] N/A Use this option when requested by your service
organization.
Chapter 10. Operating the Gateway daemon 131

132 CICS Transaction Gateway: UNIX and Linux Administration

|
Chapter 11. Operating the Client daemon
The cicscli command
This information describes how to operate the Client daemon.
The cicscli command is used to start and shut down the Client daemon, check the
availability of servers, and set other options.
The Client daemon starts automatically when you invoke any of the client
functions such as EPI, ECI, or 3270 terminal emulation; you do not need to
explicitly start the Client daemon, but you must to use the cicscli command to shut
it down. Stopping the Gateway daemon does not shut down the Client daemon.
The following table shows the functions that you can perform with the cicscli
command, and the options associated with each function:
Function Options
Start the Client daemon, and start communication with CICS servers -s
Shut down the Client daemon -i or -x
Restart the Client daemon -j or -y
Create autostart parameters for the Client daemon -r
Start client tracing -d
Use memory mapped tracing -b
Stop client tracing -o
Specify the client components to be traced -m
Set up security -c, -u, and -p
List connected CICS servers -l
Disable all output messages -q
Wait for confirmation before completion -w
Display information about the version and build level of the Client
daemon
The following sections provide examples of using the cicscli command. Full details
of the command syntax are in “cicscli command reference” on page 137.
Starting the Client daemon
To start the Client daemon, enter:
cicscli -s
To start the Client daemon and start communication with a CICS server, enter:
cicscli -s=servername
where servername is the name of a CICS server.
© Copyright IBM Corp. 1996, 2006 133
-v

Starting connections with additional servers
To start a connection to a CICS server when the Client daemon is already running,
enter:
cicscli -s=servername
where servername is the name of a CICS server.
Note: If you change and reinstall the CICS connection definition, you must stop
and restart the connection.
Shutting down the Client daemon normally
To shut down the Client daemon for all connected servers, after all outstanding
units of work have completed, enter:
cicscli -x
To shut down the session with a particular server, enter:
cicscli -x=servername
where servername is the name of a CICS server. This stops only the session with the
named server; it does not shut down the Client daemon or connections to other
servers.
Shutting down the Client daemon immediately
To shut down the Client daemon for all connected servers, without completing
outstanding units of work, enter:
cicscli -i
To shut down the session with a particular server, enter:
cicscli -i=servername
where servername is the name of a CICS server. This stops only the session with the
named server; it does not shut down the Client daemon or connections to other
servers.
If the Client daemon does not shut down completely, this might be because the
Client daemon process, cclclnt, remains active. To stop this process, enter the
command
kill -2 pid
where pid is the numeric process id of cclclnt.
Do not use the kill -9 command as this stops a process without allowing its
resources to be released; those resources remain active until you restart the system.
Restarting the Client daemon normally
To shut down the Client daemon for all connected servers, after all outstanding
units of work have completed, and then start it again, enter:
cicscli -y
cicscli -y is equivalent to cicscli -x followed by cicscli -s. This does not
re-establish server connections or trace settings.
134 CICS Transaction Gateway: UNIX and Linux Administration

Restarting the Client daemon immediately
To shut down the Client daemon for all connected servers, without completing
outstanding units of work, and then start it again, enter:
cicscli -j
cicscli -j is equivalent to cicscli -i followed by cicscli -s. This does not
re-establish server connections or trace settings.
Starting client tracing
To start tracing the Client daemon, enter:
cicscli -d
To trace the Client daemon from the startup sequence, enter the -s and -d options
together:
cicscli -d -s
The Client daemon writes trace entries to the cicscli.bin file in the /var/cicscli
subdirectory. New trace entries overwrite any existing entries in the trace file. If
required, make a backup copy of the old trace file before you start tracing.
Performance while tracing is on can be improved by using memory mapped tracing.
With memory mapped tracing, data is stored initially in memory, and flushed to
disk by the operating system’s paging mechanism. For more information, see
“Memory mapped tracing” on page 163. For important security information, see
“Security considerations for trace and log files” on page 136.
To use memory mapped tracing, do the following:
1. Turn on wrapping trace by setting the Client trace file wrap size (KB) field in
the Configuration Tool to a value greater than 0; see “Client trace file wrap size
(KB)” on page 81 for details of the field setting.
2. When you turn on tracing, specify the -b option as well as the other options,
for example:
cicscli -d -b
or
cicscli -d -m=component_list -b
Use the cicsftrc utility to format the trace file; see “Formatting the binary trace file”
on page 164.
Specifying the trace components
To specify which client components to trace, enter, for example:
cicscli -m=TRN,API.2
For information on which components you can trace, see “cicscli command
reference” on page 137.
Stopping client tracing
To stop tracing the Client daemon, enter:
cicscli -o
Trace stops automatically if you enter the cicscli -x command.
Chapter 11. Operating the Client daemon 135

Security considerations for trace and log files
The Client daemon restricts access to the client trace and log files. By default, these
are normal files, not links, called cicscli.bin, and cicscli.log, in the /var/cicscli
subdirectory. You can specify names for these files using the Configuration Tool.
The trace file
Normally, the file permissions on cicscli.bin allow only the owner, and group to
write to the file, and only the owner to read it. However, a user who has write
access to the /var/cicscli subdirectory can delete cicscli.bin regardless of the file
permissions.
If however you use the -b option (see “Starting client tracing” on page 135), every
process is given read access to the trace files.
If you do not want unauthorized users to have access to the cicscli.bin file, do not
give them write access to the /var/cicscli subdirectory. For example, a command
such as:
chmod 755 /var/cicscli
allows users to see files in /var/cicscli subdirectory but not to create, delete, or
move them.
The Client daemon prevents you from starting tracing if an unauthorized user has
deleted and recreated cicscli.bin.
Security and the error and warning log file
The file permissions on cicscli.log allow only the owner (root) and group to read
and write the file.
To improve security further:
v Set the permissions on the /var/cicscli subdirectory to restrict general access
chmod 0711 /var/cicscli
This means users cannot even see which files are in this directory.
v Allow ECI and EPI programs, and terminals, to start the Client daemon, but
allow only the root user to perform all other client administration. To do this,
restrict access to the /cicscli binary file, and allow general read
and execute access to the /var/cicscli subdirectory.
Setting up security for the Client daemon
You can use the following commands after first starting the Client daemon.
To set a user ID to use when accessing server servername, enter:
cicscli -c=servername -u=userid
where userid is the user ID and servername is the server name. (You are prompted
for the password.)
To set a password to use when accessing server servername, enter:
cicscli -c=servername -p=password
where servername is the name of the server and password is the password.
You can enter the -u and -p options together.
136 CICS Transaction Gateway: UNIX and Linux Administration

You can also specify the security parameters when you start the Client daemon or
make a connection to a server:
cicscli -s=servername -u=userid -p=password
Displaying information about the version of the Client daemon
To display information about the version and build level of your Client daemon,
enter the command
cicscli -v
Listing the connected servers
To list all the servers being used by the Client daemon, and their status, enter:
cicscli -l
Disabling the display of messages from the Client daemon
To disable the display of all messages produced by the command, enter, for
example:
cicscli -s -q
Destination for error messages
By default, the Client daemon sends error messages to the log file cicscli.log in the
/var/cicscli subdirectory.
On AIX, you can redirect these messages to another target device or file by using
the swcons command. You cannot use the -e option to send messages to the
console.
Displaying command options for the Client daemon
To display the options of the cicscli command, enter:
cicscli -?
cicscli command reference
All client control commands have options identified by a leading dash (-).
v On Linux and Solaris platforms you can replace the dash by a forward slash (/)
for all options.
v On AIX and HP-UX platforms you can replace the dash by a forward slash (/)
for all options except the ? option, where you must use a dash sign.
All options of the form -x=variable may contain spaces in the variable part, if it is
enclosed in double quotes. Double quotes within variables must be entered as \" ,
that is with a backslash preceding the double quote.
cicscli [[-s[=servername]]|[-x[=servername]]|[-i[=servername]]|[-j]|[-y] ]
[-l]
[[-d[=nnn] [-b] [-m[=components]]]|-o]
[-n|-e]
[-c=servername [-u[=userid]] [-p[=password]]]
[-w|-q]
[-v]
[-y|-j]
The options are:
-b Uses memory mapped trace. This improves performance significantly
compared with standard file I/O, but has implications for security. This
Chapter 11. Operating the Client daemon 137

option is valid only if specified when tracing is switched on, and requires
wrapping trace to be enabled. See “Starting client tracing” on page 135 for
more details.
-c=servername
Identifies the name of the server to which security information in the form
of a user ID and password is to be associated. Some CICS servers require
the user to provide security information to the server before interacting
with the server. The Client daemon prompts the user at the workstation for
a user ID and password, unless you provide them by using the -u and -p
options.
-d=[nnn]
Starts debug tracing for the Client daemon. If tracing is required while the
Client daemon is starting up, this option may be specified along with the
-s option.
nnn is the maximum size of data areas to be traced in bytes. The range is 1
through 32 767 bytes, and the default value is 512 bytes. If you are
producing a trace for your support organization, you are recommended to
set -d to at least 1000 to ensure that all relevant data is included.
The Client daemon writes trace entries to the cicscli.bin file in the
/var/cicscli subdirectory. New trace entries overwrite any existing entries
in the trace file. If required, make a backup copy of the old trace file before
you start tracing.
Use the cicsftrc utility to format the trace file. The resulting file, cicscli.trc,
is an ASCII file that you can read with a text editor. For more information
see “Formatting the binary trace file” on page 164.
-e Enables the display of Client daemon error and security messages in
pop-up windows. This option has no effect on UNIX and Linux operating
systems; pop-up messages are written to the error log.
-i Shuts down the Client daemon immediately. The Client daemon does not
wait for outstanding units of work to complete. Stopping the Client
daemon in this way can result in a loss of data at connected servers. To
stop the Client daemon normally, use the -x option.
-j Shuts down the Client daemon immediately and then restarts it.
A restart involves shutting down the Client daemon, waiting for it to shut
down, and then starting it again. cicscli -j is equivalent to cicscli -i followed
by cicscli -s. Server connections are not re-established when the Client
daemon is restarted.
The Client daemon does not wait for units of work to complete. This might
result in loss of data. To restart the Client daemon normally, use the -y
option.
-l Displays a list of all connected servers. For each server, the netname of the
server as it is known to the Client daemon is also displayed, as well as the
state of the connection to the server and the connection protocol.
-m=[components]
Specifies a comma-separated list of identifiers for components that will be
traced when tracing starts. You can specify any of the following
components:
138 CICS Transaction Gateway: UNIX and Linux Administration
ALL All components. Use it if performance allows, and consider using

the binary formatting tool to filter information. See “Formatting the
binary trace file” on page 164 for details.
API.1 The client API layer (level 1). This traces the boundary between the
Client application and the Client daemon.
API.2 The client API layer (level 1 and 2). This gives level 1 plus
additional parameter tracing.
API Synonymous with API.1.
CCL The Client daemon.
CPP The C++ class libraries.
CLI The cicscli command interface.
DEF The default components, that is the API, CCL, and DRV.1
components.
DRV Synonymous with DRV.1.
DRV.1 Protocol driver tracing level 1. This traces data sent and received
and provides supplementary information about failures.
DRV.2 Protocol driver tracing level 2. This traces internal flows through
the protocol drivers and interactions with other software
components. It is currently supported only by the CCLTCP62
protocol driver.
EMU cicsterm and cicsprnt emulators.
TRN The TRN component traces the internal interprocess transport
between Client processes. Use it if entries in the Client log refer to
functions such as FaarqGetMsg, FaarqPutMsg, or FaarqStart. TRN
is the most verbose tracing component.
v If you are not sure whether a problem is inside the Client daemon, and
you want to minimize the impact on performance, specify the DRV.1 and
API components. You can also specify these components to help to
determine which product is causing the system to lock up.
v Specify the API and CCL components if you believe that the problem is
within the Client daemon.
v If you want to diagnose an application error, and are not interested in
the Client daemon, specify only the API.2 and CPP tracepoints. The trace
contains less information, and is easier to understand.
The -m option does not start tracing in the Client daemon; it simply
specifies the components to trace. You cannot use -m while the Client
daemon is not running, so in this case you must specify the -s option as
well. Consider using wrapping trace (-b) for improved performance:
cicscli -m=component_list -b
If you specify -m with no parameters, a list of the possible component
identifiers is displayed, with an ’x’ beside each component that it is
currently enabled for tracing.
You can also specify settings for trace components using the Configuration
Tool (see “Trace settings” on page 79 in the Configuration chapter for
details). Any component tracing specified using cicscli overrides that
specified using the Configuration Tool. If component tracing is not
specified either by the cicscli command or by using the Configuration Tool,
Chapter 11. Operating the Client daemon 139

a default set of components is traced, namely: DRV.1, CCL, and API. Any
component tracing specified using the Configuration Tool overrides the
default set of components.
Note that the cicscli -d=nnn command is used to set the maximum size of
the data areas to be traced. The trace data might be truncated if you set
nnn lower than the size of data expected.
-n Disables the display of Client daemon error and security messages in
pop-up windows. This option has no effect on UNIX and Linux operating
systems; pop-up messages are written to the error log.
-o Stops tracing if it is already active.
-p=password
Sets the current password to be used when accessing the server specified
by the -c option. This password is used if the server requires a password
(and user ID) before running transactions on the client’s behalf.
For ECI applications, any user ID and password specified in the ECI
parameter block override values set by the cicscli command.
Specifying -p or -p= (that is, no password is specified) resets the associated
password to a null value.
-q Disables the display of all messages produced by the cicscli command.
-s Starts the Client daemon. No attempt is made to initiate communication
with a server unless -s=servername is specified. In this case, the Client
daemon also connects to the server using information specified in the
configuration file. The servername must correspond to an entry in the
configuration file.
-u=userid
Sets the current user ID to be used when accessing the server specified by
the -c option. This user ID is used if the server requires a user ID (and
password) before running transactions for the Client daemon.
If you do not provide the -p option, you are prompted for the password.
For ECI applications, any user ID and password specified in the ECI
parameter block override values set by the cicscli command.
Specifying -u or -u= (that is, no user ID is specified) resets the associated
user ID to a null value.
-v Displays information about the version and build level of the Client
daemon.
-w Prompts the user, before the command completes, to press the Enter key, to
confirm that information and error messages output to the screen have
been read.
-x Shuts down the Client daemon normally. If -x=servername is specified, the
connection to the server is terminated when all outstanding units of work
on the specified server have completed. If other server connections are
active, these remain unchanged.
If -x is specified without a server name, the Client daemon waits for all
outstanding units of work to complete, terminates all connections to
servers, and ends the control process. Using -x or -x=servername is the
preferred way of stopping the Client daemon.
-y Restarts the Client daemon normally.
140 CICS Transaction Gateway: UNIX and Linux Administration

Changing the system time
A restart involves shutting down the Client daemon, waiting for it to shut
down, and then starting it up again. cicscli -y is equivalent to cicscli -x
followed by cicscli -s. Server connections are not reestablished when the
Client daemon is restarted.
Using -y is the preferred way of restarting the Client daemon.
-? Causes the command syntax to be displayed.
Do not change the system time while the CICS Transaction Gateway is running.
This can give unpredictable results, and is not supported.
Chapter 11. Operating the Client daemon 141

142 CICS Transaction Gateway: UNIX and Linux Administration

Chapter 12. Terminal Emulation
This information describes how to use the cicsterm and cicsprnt programs.
Summary of Terminal Emulation commands
The cicsterm command
cicsterm
This command starts a terminal emulation session with particular options.
cicsprnt
This command starts a printer terminal session with particular options.
The cicsterm command controls 3270 terminal emulation. You can start emulator
sessions, specify terminal emulator characteristics, and the names of the keyboard
mapping and color mapping files.
You can have multiple terminal emulation sessions running simultaneously.
The Client daemon does not support 3270 field outlining for the cicsterm
command.
Window resizing is not supported. If you resize the window in which cicsterm is
running the display becomes distorted.
The CICS Transaction Server interprets cicsterm as a remote terminal. The
execution diagnostic facilities CEDF and CEDX have some restrictions on remote
terminals. Refer to your CICS Transaction Server documentation for details.
Using cicsterm
The following table shows the functions that you can perform with the cicsterm
command, and the parameters associated with each function:
Function Parameters
Start a 3270 terminal emulator -s and -r
Specify the initial transaction -t
Specify the name of the keyboard mapping file -k
Specify the name of the color mapping file -c
Define the 3270 terminal emulator characteristics -n and -m
Specify a terminal emulator that is sign-on incapable -a
Determine the print file processing -p
Specify a file to which print files are appended -f
Wait for confirmation before completing -w
Inhibit all output messages -q
Issue a single cicsterm command, with all the parameters you require, as shown in
the following example:
© Copyright IBM Corp. 1996, 2006 143

cicsterm -s=CICSTSW -t=CESN -k=mykeys.ini -c=mycols.ini
-n=cicsv123 -f=clprint.txt -q
In this example:
-s=CICSTSW
A 3270 terminal emulator is started for the server CICSTSW.
-t=CESN
The initial transaction is CESN.
-k=mykeys.ini
The keyboard mapping file is mykeys.ini.
-c=mycols.ini
The color mapping file is mycols.ini.
-n=cicsv123
The 3270 terminal emulator characteristics are defined by the terminal
definition cicsv123.
-f=clprint.txt
The print file will be appended to the file clprint.txt.
-q The display of messages output by the command is disabled.
All cicsterm parameters are optional. If you enter the cicsterm command without
any parameters, defaults are taken from the configuration file. Full details of the
parameters are given in “cicsterm command reference” on page 145.
Stopping a terminal emulator
To stop a terminal emulator, enter the string specified by the Terminal exit
configuration setting from an empty terminal screen, and then press Enter. The
default string is EXIT
cicsterm and user exits
You can use cicsterm to drive EPI user exits.
The EPI user exits, and how cicsterm can use them, are described in CICS
Transaction Gateway: Programming Guide.
cicsterm and RETURN TRANSID IMMEDIATE
When an application running from a cicsterm session issues either of the
commands:
EXEC CICS RETURN TRANSID(name) IMMEDIATE
EXEC CICS RETURN TRANSID(name) IMMEDIATE INPUTMESSAGE(data-area)
the transaction named in the TRANSID option starts immediately without any user
input. When the INPUTMESSAGE option is specified, the contents of the data-area
are passed to the new transaction, and the screen is not updated with the data-area
contents.
Issuing these EXEC CICS commands from cicsterm does not result in the
StartTranExit or ReplyExit user exits being driven. See CICS Transaction Gateway:
Programming Guide for more information.
144 CICS Transaction Gateway: UNIX and Linux Administration

Using clients for X-Window System
There are some known problems with certain clients for X-Window System (such
as Exceed). These include corruption of the text on the title bar of the window that
you are trying to display, for example, with the Configuration Tool. In some cases
the title bar might be missing. The problems are with the client used, not the CICS
Transaction Gateway.
There are two ways to solve this problem:
1. Start a window manager before launching the Configuration Tool.
The window manager HWM is shipped with Exceed.
2. Alter the Exceed configuration:
a. Launch Xconfig
b. Select screen definition
c. Set the Window Manger to native
d. Make sure Use Native WM for Embedded Clients is checked
If you use this second way you cannot run any other window manager.
Keyboard mapping in cicsterm
Keyboard mapping in cicsterm is governed by the terminal type that you are
using. Many terminal types do not support all of the function keys that can be
used in a CICS application. If cicsterm does not recognize some of the key
mappings defined by the /bin/cicskey.ini file, try using a different
terminal type. For example, on AIX systems use aixterm in preference to xterm.
cicsterm command reference
The dash (-) may be replaced with the forward slash (/) character as follows:
v On Linux and Solaris platforms you can replace the dash by a forward slash (/)
for all parameters.
v On AIX and HP-UX platforms you can replace the dash by a forward slash (/)
for all parameters except the ? parameter, where you must use a dash sign.
cicsterm [-s[=servername]|-r[=servername]]
[-t=[initialtransid]]
[-k=keyfile]
[-c[=colorfile]]
[-m[=modelname]]
[-a]
[-n=netname]
[-p=printcmd|-f=printfile]
[-q|-w]
[-?]
The options are:
-a Specifies that the terminal emulator is not sign-on capable. By default,
cicsterm creates terminal emulators that are sign-on capable.
For more information on sign-on capability, see CICS Transaction Gateway:
Programming Guide.
-c=colorfile
Identifies the name of a color mapping file to be used with the emulator;
see “Customizing the screen colors for cicsterm” on page 91 for more
details. If you omit this parameter, the environment variable CICSCOL is
Chapter 12. Terminal Emulation 145

assumed to identify the color mapping file. If CICSCOL is not defined, a
file name of cicscol.ini in the /bin subdirectory is assumed.
If the parameter is specified as -c=, that is, the color mapping file name is
omitted, the emulator runs without any color definitions.
-f=printfile
Specifies the name of a file to which the output of print requests is
appended. If you do not specify a full path, printfile is created in the
/bin directory. If the name of the file contains embedded
blanks, it must be surrounded by double quotes (“). Any double quotes
within the name of the file must be entered as backslash double quote (\“).
If neither the -f or -p parameters is specified, the Print command or Print
file configuration settings define the command, file, or default action to
take with print requests.
-k=keyfile
Identifies the name of a keyboard mapping file to be used with the
emulator; see “Keyboard mapping for cicsterm” on page 89 for more
details. If this parameter is omitted, the environment variable CICSKEY is
assumed to identify the key mapping file. If CICSKEY is not defined, a file
name of cicskey.ini in the /bin subdirectory is assumed.
-m=modelname
Specifies the name of a Model terminal definition, as known at the server
to which the emulator is to connect, to be used to define the terminal
characteristics. If neither this parameter nor -n=netname is specified, any
Model terminal definition value from the configuration file is used. If no
Model terminal definition value has been specified in the configuration file,
the server’s default terminal definition is assumed.
If the parameter is specified as -m= (that is, the modelname is omitted),
any Model terminal definition value specified in the configuration file is
ignored, and the server’s default terminal definition is assumed.
This option is case-sensitive.
-n=netname
Specifies the name of a particular terminal definition at the server that this
emulator is to be installed as. The precise interpretation of netname varies
between servers.
This option is case-sensitive.
-p=printcmd
Specifies an operating system command used to process the temporary
print file generated when print requests are received by the terminal
emulator. If the command contains embedded blanks, enclose it in double
quotes (“). Any double quotes within the command must be entered as
backslash double quote (\“).
146 CICS Transaction Gateway: UNIX and Linux Administration
The temporary print file is post-processed by appending the file name to
the command, and executing the resultant command. Thus print output
may simply be copied to a local printer, copied into a permanent file,
processed further for inclusion into a document, and so on. If the
temporary file is to be processed by a print command, the command is
responsible for deleting the temporary file.
If neither the -f or -p parameters is specified, the Print command or Print
file configuration settings define the command, file, or default action to
take with print requests.

The cicsprnt command
-q Disables the display of all messages output by the command.
-s=servername or -r=servername
Specifies the name of the server that the terminal emulator is to be
connected to. This server name must correspond to an entry in the
configuration file.
You can specify -s, or -r, but not both. If neither parameter is specified, the
first server entry in the configuration file is used.
If the parameter is specified as -s or -r (that is, no server name is
provided), and the configuration file identifies more than one potential
server to which the Client daemon can connect, the user is prompted to
select from a list of available servers. These prompts are generated even if
messages have been disabled (the -q parameter is specified).
If there is only one potential server identified in the configuration file, that
server is used and the user is not prompted.
-t=initialtransid
Identifies the initial transaction to be invoked for this terminal. If this
option is omitted, any initial transaction specified in the configuration file
is run. The string can be up to 128 characters long, specifying both a
transaction name, and parameters to be passed to the transaction. The
transaction name is the first four characters or the characters up to the first
blank in the string. The rest of the string is the parameter data.
If the parameter is specified as -t= (that is, the initialtransid is omitted),
any initial transaction specified in the configuration file is ignored.
This option is case-sensitive.
Ensure that transaction that you specify here does not require terminal
input to complete.
-w Prompts the user to press the Enter key, to confirm that messages output to
the screen (both informational and error) have been read, before the
command completes.
-? Causes the parameter syntax to be listed; any other options specified are
ignored.
The cicsprnt command controls 3270 printer terminal emulation.
An application running on a server can direct output to a printer in one of the
following ways:
v An application running from a terminal can initiate printing by sending a map
or data with the PRINT indicator set.
v A user can start a 3270 Print Terminal Emulator, at a client, using the cicsprnt
command. A 3270 Print Terminal Emulator must be started for a netname or
model terminal definition predefined in the server’s terminal tables. Output is
directed to such a device by starting a transaction against the printer device.
v At client workstations you can use the PrintScreen key, as defined by the
keyboard mapping file. However, any lines that contain only null characters are
not printed. For a ‘blank’ line to be printed, it must contain at least one space
character.
Chapter 12. Terminal Emulation 147

|
Using cicsprnt
The following table shows the functions that you can perform with the cicsprnt
command, and the parameters associated with each function:
Function Parameters
Start a 3270 print terminal emulator. -s and -r
Specify the initial transaction. -t
Define the 3270 printer terminal emulator characteristics. -n and -m
Determine the print file processing. -p
Specify a file to which print files are appended. The default location is
/bin.
Wait for confirmation before completing. -w
Inhibit all output messages. -q
Issue one print job per transaction. -j
Display help -?
Issue the cicsprnt command once with all the parameters you require, as shown in
this example:
cicsprnt -s=CICSTSW -n=P123 -t=XPRT -f=clprint.txt -q
In this example:
-s=CICSTSW
A 3270 print terminal emulator is started for the server CICSTSW.
-n=P123
The 3270 print terminal emulator characteristics are defined by the terminal
definition P123
-t=XPRT
The initial transaction is XPRT.
-f=clprint.txt
The print file to which print requests are appended is clprint.txt, in the
default location (/bin).
-q The display of messages output by the command is disabled.
You must specify at least one of these parameters:
-n=netname
-m=modelname
All other parameters are optional, and defaults are taken from the configuration
file. Full details of the parameters are given in “cicsprnt command reference” on
page 149.
If the system running the Client daemon supports DBCS, it is assumed that the
printer attached to the processor also supports DBCS. Conversely, if the system
does not support DBCS, the Client daemon will not send DBCS data to the printer.
cicsprnt and user exits
You can use cicsprnt to drive EPI user exits.
148 CICS Transaction Gateway: UNIX and Linux Administration
-f

The EPI user exits, and how cicsprnt can use them, are described in CICS
Transaction Gateway: Programming Guide.
cicsprnt and RETURN TRANSID IMMEDIATE
Unlike cicsterm, cicsprnt does not support these commands:
cicsprnt command reference
EXEC CICS RETURN TRANSID(name) IMMEDIATE
EXEC CICS RETURN TRANSID(name) IMMEDIATE INPUTMESSAGE(data-area)
For more information, refer to “cicsterm and RETURN TRANSID IMMEDIATE” on
page 144.
The dash (-) may be replaced with the forward slash (/) character as follows:
v On Linux and Solaris platforms you can replace the dash by a forward slash (/)
for all parameters.
v On AIX and HP-UX platforms you can replace the dash by a forward slash (/)
for all parameters except the ? parameter, where you must use a dash sign.
cicsprnt -m=modelname|-n=netname
[-s[=servername]|-r[=servername]]
[-t=[initialtransid]]
[-p=printcmd|-f=printfile]
[-q|-w]
[-j]
[-?]
The options are:
-f=printfile
Specifies the name of a file to which the output of print requests is
appended. If you do not specify a full path, printfile is created in the
/bin directory. If the name of the file contains embedded
blanks, it must be surrounded by double quotes (“). Any double quotes
within the name of the file must be entered as backslash double quote (\“).
If neither of the -f or -p parameters is provided, the Print command or
Print file setting in the configuration file defines the command, file, or
default action to take with print requests.
-j Specifies that cicsprnt should concatenate all EXEC CICS SEND PRINT
commands issued on a server transaction into a single print job. This print
job is issued when the transaction terminates. Otherwise cicsprnt will
generate a separate print job for every EXEC CICS SEND PRINT command
issued for a server transaction.
-m=modelname
Specifies the name of a model terminal definition, as known at the server
to which the 3270 Print Terminal emulator is to connect, to be used to
define the terminal characteristics. If this parameter is not specified, any
Model terminal definition value from the configuration file is used. If no
Model terminal definition value has been specified in the configuration file,
the server’s default terminal definition is assumed.
You must specify either the -m or the -n option, or both.
This option is case-sensitive
-n=netname
Specifies the name of a particular terminal definition at the server that this
Chapter 12. Terminal Emulation 149

3270 Print Terminal emulator is to be installed as. The precise
interpretation of netname varies between servers. For example, on TXSeries
for AIX it is a netname.
You must specify either the -m or the -n option, or both.
This option is case-sensitive.
-p=printcmd
Specifies a command used to process the temporary print file generated
when print requests are received by the terminal emulator.
If the command contains embedded blanks, the command must be
surrounded by double quotes (“). Any double quotes within the command
must be entered as backslash double quote (\“).
If neither of the -f or -p parameters is specified, the Print command or
Print file setting in the configuration file defines the command, file, or
default action to take with print requests.
The temporary print file is post-processed by appending the file name to
the command, and executing the resultant command. Thus print output
may simply be copied to a local printer, copied into a permanent file,
processed further for inclusion into a document, and so on. If the
temporary file is to be processed by a print command, the command is
responsible for deleting the temporary file.
-q Disables the display of all messages output by the command.
-s=servername or -r=servername
Specifies the name of the server that the printer is to be connected to. This
servername must correspond to an entry in the configuration file. You can
specify -s, or -r, but not both.
If neither parameter is specified, the first server entry in the configuration
file is used.
If the parameter is specified as -s or -r (that is, no servername is provided)
then, if the configuration file identifies more than one potential server to
which the Client daemon can connect, the user is prompted to select from
a list of available servers. These prompts are generated even if the -q
parameter is specified.
If there is only one potential server identified in the configuration file that
server is used and the user is not prompted.
-t=initialtransid
Identifies the initial transaction to be invoked for this printer. If this option
is omitted, any initial transaction specified in the configuration file is run.
The string may be up to 128 characters long, specifying both a transaction
name, and parameters to be passed to the transaction. The transaction
name is the first four characters or the characters up to the first blank in
the string. The rest of the string is the parameter data.
If the parameter is specified as -t= (that is, the initialtransid is omitted),
any initial transaction specified in the configuration file is ignored.
Note: Be careful that transactions that you specify either here or in the
configuration file do not require terminal input to complete.
This option is case-sensitive.
150 CICS Transaction Gateway: UNIX and Linux Administration

-w Prompts the user, before the command completes, to press the Enter key, to
confirm that messages output to the screen (both informational and error)
have been read.
-? Causes the parameter syntax to be listed; any other options specified are
ignored.
Chapter 12. Terminal Emulation 151

152 CICS Transaction Gateway: UNIX and Linux Administration

|
Chapter 13. Problem determination and problem solving
Most problems in a CICS Transaction Gateway system are caused by one of the
following:
v User errors
v Programming errors
v Configuration errors
Problem determination: preliminary checks
Before investigating a problem, check whether there is an obvious cause:
v Has the system run successfully before now?
v Have you made any changes to the configuration of the system or added new
features or programs?
v Is your CLASSPATH environment variable set correctly?
The CLASSPATH is displayed at the top of the CICS Transaction Gateway trace
output.
v Is the environment configured correctly?
v Can the Client daemon connect to the CICS server?
Use the command:
cicscli -s=servername
followed by the command:
cicscli -l
If the connection is good, this command returns the name of the server that you
specified in servername.
v Are there any messages explaining the failure?
v Are there any Java exceptions?
v Does the problem occur only at certain times?
v Can you re-create the failure?
v Do any of the available statistics help to explain the failure?
Related concepts
Chapter 15, “Statistics introduction,” on page 185
This information introduces the statistics that are available from the CICS
Transaction Gateway.
Related information
“Configure your programming environment” on page 49
For information on setting CLASSPATH
“Starting the Gateway daemon with user-specified options” on page 123
For information on starting the Gateway daemon with tracing enabled.
“Messages” on page 155
“Java exceptions” on page 159
“java.lang.OutOfMemory exception” on page 159
© Copyright IBM Corp. 1996, 2006 153

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
What to do next
If you think the problem is with the CICS Transaction Gateway, see “Diagnosing
common problems: Gateway daemon” on page 157, or “Diagnosing common
problems: Client daemon” on page 168 as appropriate. Here you will find
information on diagnosing common configuration and other errors, as well as
advice on the documentation you need to collect in specific situations.
See “Program support” on page 177 for information on how to contact IBM. See
“Documenting problems” on page 178 for the information that you will be asked
to provide.
If you think the problem is in another product, follow the problem determination
procedures provided with that product. For CICS servers, see the CICS Problem
Determination Guide.
Problems installing the product
This information describes problems that you might meet when installing or
uninstalling the CICS Transaction Gateway.
A message indicates that the CICS Transaction Gateway is
running
You might see this message when migrating from an earlier version, or when
installing the product. Check the following components, and stop them as
necessary:
Gateway daemon
This can be seen in the process list as a Java process running the CTGLaunch
class. See “Stopping the Gateway daemon” on page 125.
Client daemon
This can be seen in the process list as cclclnt. See “The cicscli command” on
page 133 for information on stopping the Client daemon.
Configuration Tool
Close the Configuration Tool.
Installation fails with a ServiceException message
Symptoms
The following message is seen during installation:
>WARNING: could not write using log service: ServiceException:
(error code = 200; message = "/tmp/cicstgInstall.log
(Permission denied)";
severity = 0; exception = >[java.io.FileNotFoundException:
/tmp/cicstgInstall.log (Permission denied)])
Cause A log file from a previous installation of the CICS Transaction Gateway
was created by the root user ID. The current installation is being attempted
by a non-root user ID that cannot update the log file; this causes the
installation to fail.
Solution
Only root can install the CICS Transaction Gateway. Change to the root
user ID and rerun the installation.
154 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
Silent installation fails
If a silent installation does not work correctly, it might not send an error to the
console that produced the problem. Appending -is:log to the
installer command causes details of any errors to be output to a file. For example,
to install silently using response file responseFile, and log errors to logFile, enter
the following command:
installer -options "responseFile" -silent -is:log logFile.txt
Problems with the Gateway daemon
Messages
The Gateway daemon writes log messages to standard output (stdout) or to
standard error (stderr). If Gateway daemon tracing is enabled, it also writes log
messages to the trace output file.
Messages have the format:
CTGnnnnt:
where nnnn is a number, and t is one of:
I for information messages, written to standard output
E for error messages, written to standard error
W for warning messages, written to standard error
To redirect all CICS Transaction Gateway messages to standard error, and send
standard error to a file called outputfile, use a command like the following:
ctgstart 2>outputfile >&2
Refer to the documentation for your operating system for more information on
redirecting output.
See CICS Transaction Gateway: Messages for an explanation of all CICS Transaction
Gateway error and warning messages.
Tracing
There are three main levels of Gateway daemon and application tracing:
Stack tracing
Trace entries are written only when a Java exception occurs. They can help
to determine the source of the exception. Use this when it is important to
maintain performance. See Figure 24 on page 156.
Standard tracing
Java exceptions and the main Gateway daemon functions and events are
traced. By default, the Gateway daemon displays only the first 128 bytes of
any data blocks (for example the COMMAREA, or network flows) in the
trace.
Debug tracing
Java exceptions and the main Gateway daemon functions and events are
traced in greater detail than with stack or standard tracing. By default, the
Gateway daemon fully outputs any data blocks in the trace. Use this only
when performance is not important or if standard tracing did not give
enough information to solve the problem.
Chapter 13. Problem determination and problem solving 155

10:38:12:262: main:S-C: java.io.IOException
10:38:12:263: main:S-C: at com.ibm.gskssl.SSLSocketImpl.socketCreate(Native Method)
10:38:12:264: main:S-C: at com.ibm.gskssl.SSLSocketImpl.create(SSLSocketImpl.java:133)
10:38:12:265: main:S-C: at com.ibm.gskssl.SSLServerSocket.(SSLServerSocket.java:109)
10:38:12:265: main:S-C: at com.ibm.gskssl.SSLServerSocket.(SSLServerSocket.java:73)
10:38:12:266: main:S-C: at com.ibm.ctg.server.GskSslHandler.initialize(GskSslHandler.java:487)
10:38:12:266: main:S-C: at com.ibm.ctg.server.JGate.main(JGate.java:941)
Figure 24. Sample Java stack trace.
Gateway daemon tracing
You can start tracing in the Gateway daemon process, or in the user application
that makes calls to the Gateway daemon (see“Tracing Java Client applications” for
more information). The following explains how to start tracing in the Gateway
daemon process.
Use options on the ctgstart command to enable and control tracing in the Gateway
daemon. For example, to enable the standard trace, use this command when
starting the Gateway daemon:
ctgstart -trace
To enable the debug trace, use this command:
ctgstart -x
You can use the Configuration Tool to define a default destination for trace output.
Otherwise, trace output is written to stderr. You can override the default
destination for trace output by using the ctgstart -tfile option. For example, the
command:
ctgstart -x -tfile pathname
starts the Gateway daemon with debug tracing enabled and writes the trace output
to the file specified by pathname.
For more information on starting the Gateway daemon with trace options, see
“Starting the Gateway daemon” on page 123.
For more information on performance considerations, see Chapter 8,
“Performance,” on page 113.
Performance considerations: Tracing, especially debug tracing, decreases
performance. The following changes were made in CICS Transaction Gateway
version 4.0 to reduce the effect of tracing on performance:
v Trace output is not written to stderr if you used the -tfile option to specify a
trace output file.
v Only the first line of any data block in the trace output is time-stamped.
v The -truncationsize and -dumpoffset options allow you to limit the size of any
data blocks that are written in the trace.
v The -tfilesize option allows you to limit the size of the trace output file.
Tracing Java Client applications
You can enable tracing in the application in two ways. Either use a Java directive
when you start the JVM, or add calls to the CICS Transaction Gateway tracing API.
Use the -D option on the java command to specify Java directives. The tracing API
156 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
comprises several static methods in the T class of the CICS Transaction Gateway.
See ″Tracing in Java client programs″ in the CICS Transaction Gateway: Programming
Guide book for further information.
JNI tracing
Use one of the following methods to enable JNI trace:
v Set the following environment variables before you start the CICS Transaction
Gateway:
CTG_JNI_TRACE
Use this environment variable to set the name of the JNI trace file. This
environment variable only defines the name of the JNI trace file; it does not
enable trace. JNI trace is output as plain text, and there is no requirement to
use a particular extension for the file name.
CTG_JNI_TRACE_ON
Set this environment variable to YES (case-insensitive) to enable JNI trace
when the CICS Transaction Gateway is started.
v While the CICS Transaction Gateway is running, use the system administration
functions. See “Administering your system” on page 126 for details of how to
enable JNI trace dynamically.
If the previous methods are not suitable, use one of the following methods:
v For Java Client applications running in local mode, use Java to launch your
application and set the system property gateway.T.setJNITFile, as shown in the
following example:
java -Dgateway.T.setJNITFile=filename application
where
– filename is the name of the file to which trace output is to be sent
– application is the application to launch
v When you start the CICS Transaction Gateway, issue the command
ctgstart -j-Dgateway.T.setJNITFile=filename
where filename is the name of the file to which trace output is to be sent. If you
do not specify a full path to the file, the location is /bin.
You cannot enable JNI trace through the Configuration Tool.
J2EE Tracing
Refer to “Tracing” on page 87 for information on using the tracing function
provided with the ECI and EPI resource adapters.
Diagnosing common problems: Gateway daemon
Problems starting the Gateway daemon
Gateway daemon fails to start with Unrecognized option:
-Xjni:arrayCacheMax=32768 message
This message indicates that an unsupported level of Java is being used. See
“Supported software” on page 19 for details of supported levels.
Code page problems
A Gateway daemon trace shows the code page in which the JVM is running. It is
displayed in the System Properties section at the top of the trace. Refer to
Chapter 13. Problem determination and problem solving 157

Appendix A, “Data conversion when using the Client daemon and a CICS server,”
on page 193 for information on finding the code page that the Client has sent to
the server.
If a process locks
To determine where the lock is happening, enable tracing in the application, in the
Gateway daemon, and in the Client daemon. See “Tracing” on page 155 for
information on tracing the Gateway daemon and the application. See “Tracing” on
page 162 for information on tracing the Client daemon, and “Diagnosing common
problems: Client daemon” on page 168 for information on how to determine
whether the lock is in the Client daemon or the server. If the lock is in the
Gateway daemon, contact your IBM support organization and provide them with
the Gateway daemon trace.
See “The Client daemon stops responding” on page 171, for information on what
to do if the Client daemon is not responding.
AIX: On some Java Virtual Machine (JVM)s you can force Java to write a stack
dump showing the states of the current threads. For example, on IBM Java SDK
you can send a SIGQUIT (-3) signal to a Java process to make it write a stack
dump to stderr. This shows the states of the current threads. Do not do this on a
working production system but only on a system which is completely locked.
Linux: The Linux threading model uses a separate process for each thread. When
a terminal-based application is sent a terminal interrupt signal, for example when a
user types CTRL+C, each process receives this signal. This means that each thread
tries to stop at the same time. Sometimes the Linux threading model cannot handle
this, and one or more threads, or processes, hangs.
To remove them, issue the command
kill -9
where is the ID of the process that has hung.
SSL problems
In general: Enable stack tracing in the CICS Transaction Gateway. This will show
you what was happening when the exception occurred. It will also give you
information about the configuration, such as the value of the CLASSPATH
environment variable. If this does not give you enough information to diagnose the
problem, obtain a standard trace and contact your IBM support organization.
JSSE:
Application receives an ″access denied″ exception: A message like the following is
received by the application:
java.io.IOException: CTG6651E: Unable to connect to the Gateway.
[address = killerb2b, port = 8050]
[java.security.AccessControlException: access denied
(java.io.FilePermission \jssekeys\testclient.jks read)]
This happens if your application does not have permission to read from the file
system containing the keystore. See Using ECI, EPI, and ESI with a Java 2 Security
Manager, in CICS Transaction Gateway: Programming Guide, for more information.
158 CICS Transaction Gateway: UNIX and Linux Administration

Java exceptions
If the application or the Gateway daemon does not handle an exception, then the
Java Virtual Machine (JVM) will write a Java stack dump. The destination for the
dump output depends on your JVM implementation; check your Java
documentation for more information.
Disable the Just-In-Time (JIT) compiler to increase the information written to the
Java stack dump. This information might include the line of Java source code
where the exception happened. How you disable the JIT compiler depends on your
JVM implementation; check your Java documentation for more information.
Figure 25 shows a sample Java stack dump taken with the JIT compiler disabled.
Exception in thread "main" java.lang.OutOfMemoryError
at java.lang.Thread.start(Native Method)
at com.ibm.ctg.server.ThreadManager.createObject(ThreadManager.java:345)
at com.ibm.ctg.server.ThreadManager.(ThreadManager.java:131)
at com.ibm.ctg.server.ManagedResources.(ManagedResources.java:106)
at com.ibm.ctg.server.JGate.main(JGate.java:895)
Figure 25. Sample Java stack dump
If the Gateway daemon handles an exception, a Java stack dump is written only if
tracing is enabled. Try to re-create the problem with tracing enabled. This should
help to show you what was happening before the exception occurred. See
“Tracing” on page 155 for more information on tracing.
Using a browser and CICS Transaction Gateway on the same workstation: If
you intend to use a browser and CICS Transaction Gateway on the same
workstation, remove ctgclient.jar and ctgserver.jar from the CLASSPATH setting. If
you do not remove them, you are likely to receive the following error when
running applications:
ERROR: java.io.IOException:
CTG6664E: Unable to load relevant class to support the tcp protocol
The reason for the error is that Java searches the CLASSPATH environment
variable before downloading classes across the network. If the required class is
local, Java attempts to use it. However, using class files from the local file system
breaks Java application security rules; therefore an exception is raised.
Java security exceptions
A message like the following is issued when using the ECI or EPI interfaces in a
Java 2 Security Manager environment:
java.security.AccessControlException: access denied
(java.util.PropertyPermission * read,write)
This might mean that your application program is trying to perform a task that is
protected by the Security Manager. Refer to ″Using ECI and EPI with a Java 2
Security Manager″, in CICS Transaction Gateway: Programming Guide, for information
on security permissions required by programs running in this environment.
java.lang.OutOfMemory exception
If this happens after the Gateway daemon has been running for a long time, then it
could be caused by a memory leak. If it happens only when the Gateway daemon
is heavily loaded, then there might be too many threads active for the available
Java Virtual Machine (JVM) memory.
Chapter 13. Problem determination and problem solving 159

On z/OS, UNIX and Linux operating systems the amount of memory available to
each process might be limited. See your operating system documentation for more
information.
Memory leak: Run a memory usage monitor against the Gateway daemon
process. If there is a memory leak, the amount of memory used by the Gateway
daemon increases over time. Make sure that all user applications that connect to
the Gateway daemon close the JavaGateway() connection object when they have
finished using it. If this does not resolve the problem, run the Gateway daemon
debug trace and contact your IBM support organization. You can use the ctgstart
-tfilesize option to limit the size of the trace output file. You can also use the
ctgstart -truncationsize option to reduce to zero the size of any data blocks that
will be displayed in the trace. This will reduce the effect on performance.
Threading considerations: You can estimate the amount of virtual memory that is
required by the CICS Transaction Gateway as follows. Add together:
v the number of Connection Manager threads
v the number of Worker threads
v the number of different protocol handlers defined and in use
Then multiply this total by the size of the Java stack and native stack allocated to
each thread by the JVM. Next, add to this value the maximum heap size defined
for the JVM and the memory footprint required by the Gateway daemon. The
memory footprint can be assumed to be approximately 50MB.
You can set the maximum number of Connection Manager threads and Worker
threads in the configuration of your CICS Transaction Gateway. See “Gateway
daemon settings” on page 53 for more information.
The way that Java allocates memory depends on your JVM implementation. Most
JVMs allow you to do the following:
v Set the maximum amount of heap memory available to the JVM by using the
-Xmx option. The default heap size specified by the CICS Transaction Gateway is
128MB.
v Set the amount of memory that Java allocates to each thread by using the -Xmso
and -Xss options. The maximum size of the Java stack and the native stack is the
sum of these two values. When using the IBM Runtime Environment, Java 2
Technology Edition, Version 5, the default values for the -Xmso and -Xss options
are 256KB, on most platforms. You should not change the Java stack and native
stack sizes from their default values.
For more information on thread limits see “The CICS Transaction Gateway
threading model” on page 113. For more information on Java memory allocation
and JVM stack sizes, refer to the IBM Developer Kit and Runtime Environment,
Java 2 Technology Edition, Version 5 Diagnostics Guide.
Related tasks
“Displaying statistics” on page 187
Use ctgadmin to display statistical information about the CICS Transaction
Gateway.
Related reference
“List of statistics” on page 189
This information describes the statistics that are available from the CICS
Transaction Gateway.
160 CICS Transaction Gateway: UNIX and Linux Administration

JVM and system dumps
JVM and system dumps provide detailed information about the internal status of
an IBM JVM, and the configuration of a running CICS Transaction Gateway.
JVM dumps provide a snapshot of a running system. System dumps provide
information about the configuration or status of the system.
Related reference
“Dump options” on page 130
Dump options are available for use with the ctgadmin -a dump command.
Problems shutting down the Gateway daemon
A normal shutdown has two stages:
1. Initiating shutdown. In this stage the Gateway daemon waits until one of the
following conditions is met:
v All work has finished.
v All Java Client applications are disconnected from the Gateway daemon.
2. Completing shutdown. The Gateway daemon stops.
New work is not allowed to start, and Java Client applications may not connect to
the Gateway daemon during a normal shutdown.
The following requests are accepted during stage 1 of a normal shutdown:
API Activity
ECI A Java Client application tries to flow an ECI request (SYNC or ASYNC)
which continues a logical unit of work.
ECI A Java Client application tries to flow an ECI Request (SYNC or ASYNC)
which commits or backs out a logical unit of work.
ECI A Java Client application tries to get a reply or wait for a reply.
EPI A Java Client application tries to flow a reply to a conversational transaction.
EPI A Java Client application tries to flow a request to disconnect or purge a
terminal.
EPI A Java Client application tries to flow a request to get event.
All other requests, or attempts to open a new connection are rejected, and an
IOException is thrown.
Determining what might have blocked a normal shutdown: The following API
calls do not stop a normal shutdown:
API Description
ECI Call type is ECI_GET_REPLY_WAIT
ECI Call type is ECI_GET_SPECIFIC_REPLY_WAIT
EPI Call type is EPI_GET_EVENT and waitState is EPI_WAIT (eg
EPIRequest.getEvent call with 2nd parameter set to EPI_WAIT will setup
the request object to wait for events.)
Any other ECI or EPI call that is waiting to finish will prevent the Gateway
daemon from quiescing.
Chapter 13. Problem determination and problem solving 161

Problems with the Client daemon
Messages
There are two types of message in the Client daemon:
1. Messages displayed to the user
2. Errors written to the Client daemon error log and trace file
The CICS Transaction Gateway: Messages book explains all error and warning
messages.
Error log messages
Any errors on the client workstation that are not caused by incorrect use of the
API are written to the Client daemon error log.
The log file is named in the configuration file. The default name is cicscli.log. The
log file is written to the /var/cicscli directory.
Help information for all messages is provided in two ASCII text files in the
/bin subdirectory. You can view these using any standard text editor:
cclmsg.hlp
Help for the end user messages, in the language you chose at installation
time.
ccllog.hlp
Help for the trace and log messages. This is provided in English only.
Errors resulting from incorrect use of the APIs simply result in error return codes
to the application. It is the responsibility of the application to notify the end user
of the error and provide guidance on corrective actions.
Messages from the Client daemon process
Pop-up messages are not displayed on UNIX and Linux systems; they are written
to the error log instead.
Tracing
Client daemon tracing is a useful problem determination tool for communication
problems. You can use the trace functions to collect detailed information on the
execution of a certain function or transaction. A trace can show how the execution
of a particular activity is affected by, for example, the execution of other tasks in a
CICS system. Each trace entry has a time stamp, which provides information on
the time taken to perform certain activities.
To learn how to turn tracing on, see “Starting client tracing” on page 135.
For information on specifying the components of the Client daemon to be traced,
see the cicscli -m command.
The output from the trace function is a binary trace file called, by default,
cicscli.bin in the /var/cicscli subdirectory. You can specify a different name for this
file, using the Configuration Tool. However, you cannot change the .BIN extension.
Using the Client trace file wrap size (KB) configuration setting, you can specify
that the binary trace file should wrap into a second trace file, and you can also
specify the maximum size of these files.
162 CICS Transaction Gateway: UNIX and Linux Administration

To read the trace, run the cicsftrc utility to convert the binary file or files into a text
file. This text file is called cicscli.trc by default. The default trace files are:
cicscli.bin
The binary trace file produced by running the Client daemon trace.
cicscli.wrp
The second binary trace file if wrapping of client trace is enabled.
cicscli.trc
The name of the text trace file produced when the binary trace file is
converted to a text file using the cicsftrc utility.
cicscli.bak
The backup file of the binary trace file. A backup file is produced from any
existing .BIN file when you turn tracing on.
cicscli.bbk
The backup of the first binary trace file if memory mapped tracing is
enabled.
cicscli.wbkn
The backup of subsequent binary trace files, if memory mapped tracing is
enabled, where n is the number of the original .WRP file.
See “Formatting the binary trace file” on page 164 for information on the trace
conversion utility.
Wrapping the Client daemon trace
You can control the size of the binary trace file by specifying that it wraps into a
second trace file. Use the Client trace file wrap size (KB) configuration setting to
turn on wrapping trace; specify the maximum size of the wrapping trace (in
kilobytes). If this value is 0 (the default), wrapping trace is not turned on.
When wrapping trace is turned on with standard I/O tracing, two files (called
cicscli.bin and cicscli.wrp) are used. Each file can be up to half the size of the
Client trace file wrap size (KB) value.
Memory mapped tracing
If you enable wrapping trace, you can use the -b switch when you issue the
cicscli command to turn tracing on. This specifies that memory mapped trace
files should be used.
With memory mapped tracing, the operating system’s paging mechanism is used
to swap data between memory and the trace file. This improves performance
significantly when compared to standard file I/O, because the trace file is opened
and written to less frequently. Because the operating system is responsible for
flushing data to disk, data is not normally lost if an application terminates
unexpectedly. However, if the operating system itself fails, data can be lost, and the
trace file can be corrupted. If you are diagnosing problems where the server fails
and needs to be restarted, use standard I/O tracing instead of memory mapped
tracing.
If you use memory mapped tracing, the size of the trace files is limited to 10 MB,
and in addition to cicscli.bin and cicscli.wrp, you might see a series of files of the
form cicscli.wrp1, cicscli.wrp2...cicscli.wrpn, where n is the number of files needed
to hold the total amount of trace data specified in the Client trace file wrap size
(KB) field of the Configuration Tool; see “Client trace file wrap size (KB)” on page
81 for the maximum amount of data that can be specified. The trace formatter
Chapter 13. Problem determination and problem solving 163

finds all files in the sequence when you format the binary files. Memory mapped
tracing uses up to 10 MB of virtual storage.
See “Starting client tracing” on page 135 for details of how to issue the command,
and “Security considerations for trace and log files” on page 136 for important
information on security.
Formatting the binary trace file
If you are using memory mapped tracing, note that data is not always written to
disk immediately. As a consequence, turn tracing off before you format the binary
trace file, to ensure that all data is flushed to disk.
You use the Binary Trace Formatter utility cicsftrc to convert the binary trace file
cicscli.bin to ASCII text. The utility has the following parameters:
-m=list of components
Specifies that only trace points from the listed components are written to the
text file. The components you can specify are the same as for cicscli -m; see the
cicscli -m command. If -m is not specified, all trace points in the binary trace
are written to the text file.
-w[=filename]
Indicates that there are two or more binary trace files to format and then
concatenate (that is, the binary files were created with a wrapping trace). If no
file name is specified with the -w parameter, cicsftrc assumes that the name of
the second trace file is cicscli.wrp.
-n Indents entry and exit points in the test trace file to make it more readable. By
default, indentation is turned off.
-d Specifies detailed trace formatting. If you are using EPI calls, cicsterm or
CICSPRINT, an approximation of the screen layout will be included in the
trace. If you are using a TCP62 driver, -d also provides formatted output of the
MPTN and SNA data flows.
-i=filename
Specifies the name of the input (binary) trace file, which is cicscli.bin by
default.
-o=filename
Specifies the name of the output (text) trace file. If no -o parameter is specified,
the name of the text trace file is assumed to be cicscli.trc.
-f Overwrite any existing files.
-s Do summary trace formatting. Summary trace formatting is controlled by a
template file (cclsumtr.txt), which is read in at initialization time. It formats key
trace points, and shows for example the flow of user API calls, the progress of
calls through the Client daemon, and network flows to the server. For the most
detailed results, specify the API.2 component when you define the components
to be traced. Summary tracing provides an overview; use it as requested by
your IBM support organization.
Note: Versions of the CICS Transaction Gateway earlier than 5.0.1 cannot format
binary trace files produced by this version.
Figure 26 on page 165 shows an example summary trace.
164 CICS Transaction Gateway: UNIX and Linux Administration

-->Sample of API summary trace taken with API.2 and DRV options.
[Process ,Thread ] Time API Summary CCLCLNT Summary Comms Summary
=============================================================================================================
...
...
...
[000000bf,0000017c] 12:08:32.190 --->[7315] CCL3310 ECI Call type ECI_SYNC, UOW=0
[00000089,000000a4] 12:08:32.290 -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=89
[00000089,00000063] 12:08:32.400 [4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,000000a4] 12:08:32.551 -S->[4410] CCL4411 TCP/IP (to STEMPLAR) send data: Length=94
[00000089,00000168] 12:08:32.581

Command = Erase/Write, so clearing main screen
Command2 = Read Modified
WCC = 0x32 ( Free Kbd,80 char)
Set Buffer Address to (1,2)
Insert Cursor @ (1,2)
Set Buffer Address to (1,1)
Start Field Extended (Unprotected,Alphanumeric,Display,not-pen-detectable,Foreground Colour Green)
Data : ’ ’
Insert Cursor @ (1,3)
Set Buffer Address to (2,1)
Data : ’User ’
.....
.....
.....
.....
Set Buffer Address to (24,49)
Start Field Extended (Autoskip (Prot+Num),Display,not-pen-detectable,Foreground Colour Turquoise)
Data : ’9’
Set Buffer Address to (24,51)
Start Field Extended (Unprotected,Alphanumeric,Intense,pen-detectable,Foreground Colour Red)
Data : ’Messages ’
1 2 3 4 5 6 7 8
12345678901234567890123456789012345678901234567890123456789012345678901234567890
>+----------------------------------------------------------------------------------+
01| - |
02| uSTATUS. . :uEnter one of the following: |
03| u |
04| uABend EXtract READPrev WAit |
05| uADdress FEpi READQ WRITE |
06| uALlocate FOrmattime RECeive WRITEQ |
07| uASKtime FREE RELease Xctl |
08| uASSign FREEMain RESetbr |
09| uBif Getmain RETRieve |
10| uCAncel Handle RETUrn |
11| uCHange IGnore REWrite |
12| uCONNect INquire SENd |
13| uCONVerse ISsue SET |
14| uDELAy LInk SIGNOFf |
15| uDELETE LOad SIGNON |
16| uDELETEQ PErform START |
17| uDEQ POP STARTBr |
18| uDUmp POSt SUspend |
19| uENDbr PUsh SYncpoint |
20| uENQ READ Unlock |
21| uENTer READNext Verify |
22| u |
23| uPFu1-Help u2-HEX u3-End u4-EIB u5-Variables |
24| u6-User u9-Messages |
+----------------------------------------------------------------------------------+
| 1BþC000 STEMPLAR |
+----------------------------------------------------------------------------------+
12345678901234567890123456789012345678901234567890123456789012345678901234567890
1 2 3 4 5 6 7 8
Figure 27. Screen capture from a formatted trace file
The formatter lists the commands which built the screen, and shows an
approximation of the screen.
Format of trace entries
The entries in the Client daemon trace file have the following format:
time [process id,thread id] [number] component trace message
data
where:
time
The time the entry was written, to millisecond accuracy.
[process id, thread id]
Process id is a unique number that the operating system uses to identify a
process. Thread id is a unique number that the operating system uses to
identify a thread within a particular process.
166 CICS Transaction Gateway: UNIX and Linux Administration

[number]
A number that uniquely identifies the particular trace entry. This helps your
support organization in the diagnosis of serious problems.
[component]
The component of the product to which this entry applies.
trace message
The trace message number and text.
data
Some trace entries include a dump of key data blocks in addition to the trace
message.
Sample Client daemon trace: Figure 28 shows the trace information recorded
during the successful connection of a Client daemon to a CICS server using the
TCP/IP protocol. The trace was generated using the commands:
cicscli -s=cicstcp -dcicscli
-o
17:03:57.580 [0000080c,00000908] [1007] TRC:CCL1042 *** CICS Client for Windows v7 Service Level 00 - service trace started ***
17:03:57.590 [0000080c,00000908] [2183] CCL:CCL2048 Maximum trace data size set to 512
17:03:57.600 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds
17:03:58.612 [0000080c,00000908] [2030] CCL:CCL2106 Comms Event : LINK-UP
17:03:58.622 [0000080c,00000908] [2019] DRV:CCL2055 Connection with server established (linkID=1)
17:03:58.622 [0000080c,00000908] [2035] CCL:CCL2109 Send server TCS data
17:03:58.632 [0000080c,00000908] [3214] CCL:CCL3251 Comms Allocate request (LinkId=1, Tran=’CCIN’)
17:03:58.632 [0000080c,00000908] [3217] CCL:CCL3238 Comms Allocate completed (LinkId=1, ConvId=1, Rc=0)
17:03:58.632 [0000080c,00000908] [2127] CCL:CCL2143 CommsBegin - OK
17:03:58.632 [0000080c,00000908] [3100] CCL:CCL3113 CCIN install request: ApplId=’* ’, Code page=819
...
...
...
17:04:00.625 [0000080c,00000908] [3102] CCL:CCL3114 CCIN install response: ApplId=’@0Z8AAAA’, Code page=8859-1, Rc=0
17:04:00.625 [0000080c,00000908] [3241] CCL:CCL3255 Comms Complete request (ConvId=1)
17:04:00.635 [0000080c,00000908] [3244] CCL:CCL3246 Comms Complete completed (ConvId=1, Rc=0)
17:04:00.635 [0000080c,00000908] [3218] CCL:CCL3252 Comms Deallocate request (ConvId=1)
17:04:00.645 [0000080c,00000908] [3221] CCL:CCL3239 Comms Deallocate completed (ConvId=1, Reason=0, Rc=0)
17:04:00.645 [0000080c,00000908] [2042] CCL:CCL2114 Processed TCS Reply - Server connected
17:04:00.645 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds
17:04:00.655 [0000080c,00000908] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds
17:04:00.664 [0000080c,00000908] [1004] TRC:CCL1043 *** Service trace ended ***
Figure 28. Sample Client daemon trace
Message ID
Explanation
CCL1042
Start of trace message. Each time a trace is started, a backup of the old
trace file is created, and the trace file is overwritten. You can delete the file
when required. Check the time stamp to ensure that you are reading the
correct trace.
CCL2048
Maximum trace data size is at the default size of 512 bytes. You can
modify this size by specifying the size value in the start command for the
client trace; see the cicscli -d command.
CCL3251
The client sends a CCIN transaction to the server to install its connection
definition on the server.
CCL3238
A conversation ID has been successfully allocated. If more than one
conversation is active, use the conversation ID to distinguish between
them.
Chapter 13. Problem determination and problem solving 167

CCL3113
The client sends a CCIN transaction to the server with Appl ID set to * to
install its application. The Appl ID is specified in the configuration file as
Client=*. This requests the server to dynamically generate an Appl ID that
is unique within the CICS server system.
CCL3114
This shows the dynamically generated Appl ID.
CCL1043
End of trace message.
Figure 29 shows trace information recorded when we tried to connect to a CICS
server over TCP/IP using an invalid port number. The port number specified in
the configuration file file was not defined in the services file of the server. Hence,
the connection could not be established.
16:16:41.562 [0000093c,000008ec] [1007] TRC:CCL1042 *** CICS Client for Windows v6 Service Level 00 - service trace started ***
16:16:41.572 [0000093c,000008ec] [2183] CCL:CCL2048 Maximum trace data size set to 512
16:16:41.582 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is 0 seconds
16:16:41.612 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is -1 seconds
16:16:41.622 [0000093c,000008ec] [3207] CCL:CCL3249 Comms Open request (Server=CICSTCP, Driver=CCLIBMIP)
16:16:41.622 [0000093c,000008ec] [4408] DRV:CCL4413 CCL4413 TCP/IP (to CICSTCP) address=192.113.36.200, port=1089, socket=3
16:16:41.622 [0000093c,000008ec] [3210] CCL:CCL3236 Comms Open completed (Server=CICSTCP, LinkId=1, Rc=0)
16:16:41.633 [0000093c,000008ec] [2114] CCL:CCL2142 GetNextTimeout timeout is 3660 seconds
16:16:41.633 [0000093c,000008ec] [1004] TRC:CCL1043 ***Service trace ended ***
Figure 29. Client daemon trace: using an invalid port number
Message ID
Explanation
CCL4413
Shows the port number used for this connection request.
You must check your definitions in the SIT on the server, the configuration file on
the workstation, and the services file for the port number specified.
You must provide a valid port number or use the default value.
Diagnosing common problems: Client daemon
This section provides information to help you solve some common problems with
the Client daemon. The problems are discussed under the following headings:
v “Starting clients and terminals”
v “TCP/IP communication problems” on page 169
v “APPC communication problems” on page 170.
v “TCP62 communication problems” on page 170
v “Traps” on page 171
v “The Client daemon stops responding” on page 171
v “CICS server problem determination” on page 173
v “Communication problem determination” on page 174
For information on error messages, refer to CICS Transaction Gateway: Messages.
Starting clients and terminals
The following are solutions to problems that can occur when starting clients and
terminals:
A cicsterm request has gone to the wrong server
168 CICS Transaction Gateway: UNIX and Linux Administration

If you do not specify the -s=servername option on the cicsterm command, the Client
daemon sends a cicsterm request to either of:
v the default server
v the first server listed in the configuration file, even if it is not yet activated.
The servername should be as specified in the configuration file.
Problems loading protocol drivers
The message ″Cannot load protocol driver″ in the cicscli.log file means that you are
trying to use a protocol driver that does not exist. Check your configuration file
file to make sure that the driver name is correct, and is supported in this release.
The Client daemon can connect to the server, but cicsterm cannot
In other words, cicscli -s=servername connects successfully, but cicsterm
-s=servername does not. Check the following:
v Is the CTIN transaction defined on the server?
v Does cicsterm-a successfully install a terminal that is not sign-on capable?
cicsterm attempts to install a sign-on capable terminal by default. If the -a option
works, the server probably does not support sign-on capable terminals.
CICS servers require APAR fixes to support terminal sign-on capability; see
“Supported software” on page 19. Refer to the CICS Transaction Gateway
README file for the latest details and check the PTFs for the CICS servers.
See “APARs and fixes” on page 180 for general information about APARs.
An XTERM session stops working after the CICS Transaction Gateway
is upgraded
The problem is caused because some files might have changed location between
versions. The solution is to open a new XTERM window.
TCP/IP communication problems
The following are solutions to problems that can occur when communicating over
TCP/IP:
Message CCL4404 TCP/IP (to ’CICSTCP’) unable to resolve name: RC=2
The CICS server, in this example CICSTCP, could not be resolved by the TCP/IP
protocol driver. Ensure that your domain name server and router address
information is correct, and that any names and IP addresses in the TCP/IP
etc/hosts file are correct.
Use the TCP/IP ping or nslookup commands to see if TCP/IP can resolve the
hostname.
CCIN not recognized, CTIN not recognized
The CCIN transaction installs your Client daemon definition on the CICS server.
The CTIN transaction installs your client terminal definition on the CICS server.
These transactions must be available on the CICS server if it supports the EPI,
because the EPI implies CICS 3270 terminal emulation and CICS 3270 printer
Chapter 13. Problem determination and problem solving 169

|
|
|
emulation. For information on which CICS servers support EPI and hence CICS
3270 emulation, see Table 1 on page 25. You can ignore these messages if your
CICS server does not support the EPI.
A cicsterm command for a mainframe CICS server failed
cicsterm and cicsprnt use CICS 3270 emulation. Some mainframe CICS servers do
not support CICS 3270 emulation. For information on which CICS servers support
CICS 3270 emulation, see Table 1 on page 25.
APPC communication problems
The following are solutions to problems that can occur when communicating over
APPC:
Error message CCL4678E received
Linux generates this message if environment variable LD_PRELOAD is not
defined. Refer to “Configuring Communications Server for Linux” on page 43 for
configuration details. For security reasons LD_ variables are not inherited by the
root user.
SNA error log: The SNA error log can help your support organization to
diagnose problems. In a default installation, the log is located as follows:
AIX: /var/sna/sna.err
Linux on zSeries: /var/opt/ibm/sna/sna.err
Linux on POWER: /var/opt/ibm/sna/sna.err
Linux on Intel: /var/opt/ibm/sna/sna.err
Solaris: /var/opt/sna/sna.err
The user who starts the Client daemon should be a member of the sna group,
otherwise the Client daemon cannot write to the SNA error log; in this situation
the Communications Server for Linux on zSeries writes a message to
/var/log/warn.
TCP62 communication problems
CCL5820 TCP62: Attempt to open server ’server1’ which is a
duplicate of ’server2’
Multiple identical server definitions are not permitted in the configuration file of
the CICS Transaction Gateway. The combination of fields that identify a server, and
must therefore be unique is as follows:
Protocol
Fields in ctg.ini
TCP/IP
Hostname or IP address and Port.
SNA Partner LU name, Local LU name and Mode name.
TCP62 Partner LU name, Local LU name and Mode name.
This ensures that every connection that the CICS region and the network protocol
see is represented by a unique server definition in the configuration file. If you
have existing Client applications that use different server names to send requests
170 CICS Transaction Gateway: UNIX and Linux Administration

to the same CICS region, you need to write a user exit to redirect requests. This is
demonstrated in sample user exits ecix2.c and epix2.c; see /
samples/samples.txt.
An open, idle connection drops after several minutes.
If a cicsterm is open, this will be seen as a ’server down’ message flashing up on
the screen, which disappears when the server is reconnected and the terminal
reinstalled. This might be because UDP packets are not being sent. If a firewall is
present, check that it is correctly configured to allow UDP packets; see “Firewall
implications” on page 41 for more information.
Traps
dbx and dbg
If the Client daemon, or a user application terminates unexpectedly, it may
produce a core dump. You can get stack traces by attaching dbx (dbg on Linux
operating systems) to the core dump. The procedure is similar to attaching dbx
to a running process—see dbx tool for details. Consult the documentation
supplied with your operating system for full details.
When you attach dbx to the core dump you might get errors saying that the
data is truncated. If so, check the following:
v That there is enough space in the file system for the core dump
v That user ID settings do not limit the size of the core dump
The Client daemon stops responding
This section discusses what to do if you think the Client daemon has stopped
responding, for example because:
v API, ECI and EPI calls do not complete, or
v cicsterm hangs
Check that your CICS Transaction Server is working correctly, for example by
looking at the CICS log. Insufficient storage on the CICS region may cause CICS
Transaction Gateway to hang.
To test whether CICS Transaction Gateway has stopped responding, issue cicscli -l
from the command line. If the call hangs then CICS Transaction Gateway is not
responding. See “If a process locks” on page 158, for information on what to do if
the Gateway daemon is not responding.
Try to reproduce the problem with tracing turned on. Take a client trace with as
many components as possible active. As a minimum you need the API, DRV and
CCL tracepoints; add TRN if possible. (Use wrapping trace if you do not want the
trace file to get too large; see “Tracing” on page 155.) The summary trace shows
whether the client or user application has stopped responding, and gives an
indication as to whether the problem is in the client or server.
If you can reproduce the problem, have details of how to reproduce it available for
your support organization. If you cannot reproduce the problem, have available
details of the circumstances that led up to the hang, for example:
v Does it hang only when the system is under heavy load?
v Does it hang only when there are many concurrent users?
v Does it hang only under a particular configuration, or after a known sequence of
events?
Chapter 13. Problem determination and problem solving 171

All UNIX and Linux systems
Run ps -ef and ipcs -qa on the system, piping the output to a file. This lists
the following:
v Processes on the system
v All UNIX and Linux IPC queues
v Amount of data in the queues
v Owner of the queues
This information is useful because the client uses IPC queues for internal
communication.
Check also that your message queues are correctly configured; see
“Configuring message queues” on page 46.
AIX operating system
Use the System Management Interface Tool (SMIT) to take an operating system
trace of the failure.
Use the syscalls event set and ipcs related trace options. Format it to show
pids, tids, current system calls, and elapsed time options. Consider increasing
the buffer file settings.
dbx tool
You can attach the dbx tool to a process that has locked, to find out what
the process is doing. (Check that dbx is installed on your system, and that
you have authority to connect to a process.) This example shows how to
attach dbx to the Client daemon cclclnt. You can adapt the example to
find out why a user application has locked.
Important: Attaching dbx to a process sometimes causes the process to
lock or terminate. Use it only if you are sure the process has
locked.
Type the following command to find out the process id (pid):
ps -ef | grep cclclnt
Information about the process is displayed:
root 26864 27348 3 11:06:51 pts/2 0:00 grep cclclnt
bartfast 28266 1 0 11:06:46 pts/0 0:00 cclclnt
Using the information provided by the ps command, type this to attach
dbx to the process:
dbx -a 28266 ./cclclnt
You should now see something like this:
172 CICS Transaction Gateway: UNIX and Linux Administration
Waiting to attach to process 28266 ...
Successfully attached to cclclnt.
Type ’help’ for help.
reading symbolic information ...warning: no source compiled with -g
stopped in _pthread_ksleep at 0xd0139164 ($t2)
0xd0139164 (_pthread_ksleep+0x9c) 80410014 lwz r2,0x14(r1)
To get a stack back trace of the current thread, issue the where command:

_pthread_ksleep(??, ??, ??, ??, ??) at 0xd0139164
_pthread_event_wait(??) at 0xd01395c0
_cond_wait_local(??, ??, ??) at 0xd0135494
_cond_wait(??, ??, ??) at 0xd0135998
pthread_cond_timedwait(??, ??, ??) at 0xd0136368
OsEventTimedWait() at 0xd00a78b4
.() at 0x100005b8
_pthread_body(??) at 0xd012f358
To list all threads in the cclclnt process, type thread :
thread state-k wchan state-u k-tid mode held scope function
$t1 wait 0xc0000100 running 21793 k no sys
>$t2 run blocked 32425 k no sys _pthread_ksleep
To make thread 1 the current thread, type thread current 1.
To get a stack back trace of thread 1, type where. The screen looks like this:
.() at 0x1000c784
.() at 0x10000ae0
.() at 0x10000ae0
.() at 0x100003f4
To close dbx, type quit.
Solaris
Run truss against the hung process; see the operating system documentation
for relevant parameters. Specify options to follow forked calls, trace arguments
to system calls, and show the environment strings to operating system calls.
Ensure that the /etc/system file allows sufficient queue entries; see
“Configuring message queues” on page 46. If the value is too low, the client
may freeze while waiting for a queue entry to become available.
Solaris system notes:
1. Whenever you change the /etc/system file, you must
restart your system for the changes to take effect.
2. Changes to your system may not work if your
workstation has less than 32MB of memory; the
recommended minimum is 64MB.
CICS server problem determination
The most important facilities for problem determination on CICS servers are:
v Traces
– auxiliary
– internal
v Dumps
v CICS message logs
v Statistics information
v Monitoring information
v Execution diagnostic facility (EDF)
v CICS-supplied transactions, CEBR and CECI
v Independent software vendor (ISV) tools
Chapter 13. Problem determination and problem solving 173

Information about these facilities is given in the Problem Determination books for
the individual products (see “CICS Transaction Server publications” on page 212).
You may need to contact the server system administrator for more information, for
example, about a CICS server error log.
The following shows the error message prefixes for CICS products:
CCL CICS Universal Client
CTG CICS Transaction Gateway
DFH CICS on CICS on System/390 ®
and z/OS
ERZ CICS Transaction Server for Windows, and TXSeries
AEG CICS Transaction Server for iSeries.
CPMI tasks lock in CICS Transaction Server for z/OS: If a CPMI (or equivalent
mirror transaction) task locks in your CICS region, it is possibly because you have
reached the MAXTASKS limit of your CICS region. This prevents the mirror
program from sending data back to the Client daemon, which appears to hang.
The problem typically occurs when CICS has a high number of concurrent
transactions. A solution is to put the mirror transaction in a TranClass that has a
MAXACTIVE lower than the MAXTASKS of your CICS region. All new requests to
the CICS region are queued, and CICS can continue to process current requests.
The value you specify for MAXACTIVE depends on your installation, and other
tasks running in the region.
Communication problem determination
Even a small telecommunications network is a very complex system in which all
components depend on one another. If one component fails and presents incorrect
information to the other components, the latter may fail even more severely than
the former. Sometimes the failure may be considerably delayed, and the error
indicator may be lost before the error is detected. Thus, it is sometimes difficult to
analyze a problem in the communication part of a system.
The Client daemon generates various messages associated with the use of the
supported communication protocols and the associated products. Refer to CICS
Transaction Gateway: Messages for a list of these messages and their explanations.
The communication products themselves generate error messages. For details of
these, and information on troubleshooting, you should refer to the documentation
for the communication product. The following sections summarize useful
commands and utilities for problem determination.
TCP/IP-providing products: TCP/IP provides the following diagnostic tools:
arp Displays and modifies the IP-to-Ethernet or token ring physical address
translation tables used by address resolution protocol (ARP).
hostname
Displays the host name of your workstation.
ifconfig
Displays all current TCP/IP network configuration values. This is helpful if
you have to find out if an IP interface is active. The Linux equivalent of
IPCONFIG.
ipconfig
Displays all current TCP/IP network configuration values. This is helpful if
you have to find out if an IP interface is active.
174 CICS Transaction Gateway: UNIX and Linux Administration

|
netstat
Displays protocol statistics and current TCP/IP network connections. This
helps you obtain information about your own IP interfaces, for example, to
list IP addresses and TCP/IP routing tables in use at your workstation.
nslookup
Displays information from Domain Name System (DNS) name servers.
ping Verifies connections to a remote computer or computers.
traceroute
Traces the TCP/IP path to a requested destination. It is useful for
determining whether there is a problem with one of the intermediate
nodes.
For more information on these utilities, refer to the online help for TCP/IP.
APPC-providing products: This section describes problem determination in
products involved in APPC communication.
VTAM Buffer Trace: You can use VTAM buffer tracing to record the flow of data
between logical units in the CICS environment. The trace entries include the
netname of the terminal (logical unit) to which they relate. For details on VTAM
buffer tracing and other VTAM problem determination functions, see the
appropriate book in the VTAM library.
The APING utility: In an APPC environment, you can use the APING utility to test
a connection. APING exchanges data packets with a partner computer over APPC
and times how long the data transfer takes. It can be used to get a first estimate of
the session setup time between two computers and the throughput and turnaround
time on that APPC session. You can use APING to determine whether a session
can be set up between two computers and to display extensive error information if
session allocation fails. APING consists of two transaction programs: APING,
which runs on the client side, and APINGD, which runs on the server side.
Checking client and host configuration: If the SNA product on the Client daemon
machine, and the host are both correctly configured, you should be able to activate
the connection between them. Follow the steps below to activate the connection;
you do not need to start the client first.
1. Start the node on the SNA product on the Client daemon machine.
2. Use the CEMT transaction to acquire the connection. Type CEMT I CON. The
screen will look similar to this:
I CON
STATUS: RESULTS - OVERTYPE TO MODIFY
Con(SIMD) Net(PYKS88BA) Ins Rel Vta Appc
Con(SYSB) Net(IYCKZCCV) Ins Rel Vta Appc
SYSID=SYSA APPLID=IYCKZCCU
RESPONSE: NORMAL TIME: 12.25.04 DATE: 03.01.01
PF 1 HELP 3 END 5 VAR 7 SBH 8 SFH 9 MSG 10 SB 11 SF
3. Overtype Rel with ACQ, to acquire the connection.
If you cannot acquire the connection, SNA is wrongly configured on the product or
the host.
Chapter 13. Problem determination and problem solving 175

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
IBM Communications Server for AIX and Linux: IBM Communications Server
writes a log file as follows:
AIX systems
/var/sna/sna.err
Linux on zSeries systems
/var/opt/ibm/sna/sna.err
Linux on POWER systems
/var/opt/ibm/sna/sna.err
Linux on Intel systems
/var/opt/ibm/sna/sna.err
The IBM support organization needs the file if you have SNA errors that you
cannot resolve. For information about sense codes, use the following management
command:
sna -getsense sensecode
Mirror transaction does not time out
The default ECI mirror transaction (CPMI or CSMI) uses a PROFILE of
DFHCICSA. This profile has an RTIMOUT value of NO. This means that if an ECI
request is suspended in CICS during an extended unit of work, the mirror
transaction never times out. To enable timeout in these situations:
1. Define a new mirror transaction with SPURGE=YES, and which specifies a
PROFILE containing an RTIMOUT value other than NO.
2. Specify this new mirror transaction as the Transid in the ECIRequest using a
call type of ECI_SYNC_TPN.
In these situations, if no response is received from the client after the timeout
period has elapsed, CICS purges the mirror transaction and rolls back the
associated unit of work.
Problems with Client applications
On Linux systems, your application might fail to start with a message like the
following:
relocation error: ./ecib1: undefined symbol:
__6CclBufPCcQ26CclBuf12DataAreaType
This can occur with C++ applications compiled with GNU C/C++ compiler (gcc)
2.96. This compiler is not supported; recompile your application with a supported
compiler listed at “Supported software” on page 19.
Telnet clients
If you run the CICS Transaction Gateway over Telnet, certain Telnet clients can
cause problems with the display. For example, your Telnet session might truncate
message lines over a certain length. This is usually a problem with the Telnet client
that you are using, or the terminal type that you are emulating. Currently there is
no solution to this problem.
176 CICS Transaction Gateway: UNIX and Linux Administration

Problems running the Configuration Tool
Program support
If the Configuration Tool does not display all characters correctly, check the console
where CICS Transaction Gateway was invoked. If the operating system has issued
warning messages about fonts, check that all fonts needed for code page for the
current locale have been installed. Refer to the documentation supplied with your
operating system and JRE for information on which font packages are required for
which locales.
If you need to contact your IBM support organization, first refer to the Service and
Support card supplied with the product for details of the support available to you,
or visit our Web site at: www.ibm.com/software/cics/ctg and follow the Support
link.
This section provides guidance on reporting problems, detailing the information
you should collect to assist your support organization. It also explains how the
problem is handled through to resolution and the provision of a fix.
Reporting problems
Before reporting your problem to the support organization try to ensure that the
error is actually occurring within your CICS Transaction Gateway system, even if
you are unsure whether the problem is due to the CICS Transaction Gateway itself.
In practice, many errors reported to support organizations turn out to be user
errors, or they cannot be reproduced, indicating just how difficult it can be to
determine the precise cause of a problem. User errors are mainly caused by faults
in application programs or by errors in setting up systems.
The ability of the support organization to resolve your problem quickly depends
on the quality of the information you provide to them. For this reason it is good
practice to collect and organize problem data before making the initial contact.
Summarize your problem and the documentation/information you collect on a
problem reporting sheet. This sheet provides a valuable summary to the support
organization, and a copy will be useful for your own records.
Level-1 support
If this is your first contact regarding this problem a unique incident number will
be assigned. A Problem Management Record (PMR) is opened on the RETAIN ®
database system, where all activity associated with your problem is recorded. The
PMR remains “open” until it is solved.
Make a note of the incident number on your copy of the problem reporting sheet.
You will be expected to quote the incident number in all future correspondence
relating to this problem.
Your initial communication with the support organization is through a Level-1
representative, who uses the keywords that you have provided to search the
RETAIN database for problems with similar symptoms. If your problem is found
to be one already known to the support organization, and a fix has been devised
for it, you will be advised of the availability of corrective service software that you
can install to overcome the problem, as described in “Obtaining the fix” on page
180. If the RETAIN search is unsuccessful, the problem is passed on to a Level-2
Chapter 13. Problem determination and problem solving 177

epresentative who will contact you for more information about your problem, to
start a more detailed investigation of the cause.
Level-2 support
Let the Level-2 representative know if any of the following events occurred before
the problem appeared:
1. Changes in level of the CICS Transaction Gateway, compiler or associated
licensed programs
2. Corrective service software and fixes applied to workstation software
3. Problem Tracking Fixes (PTFs) applied to other associated products
4. Additional features used
5. Application programs changed
6. Unusual operator action.
At this stage you may be asked to supply more details or documentation. If this
happens, the PMR is updated to show any documentation you have submitted.
Based on the information you supply, the investigation then carried out can
determine whether the cause of your problem is new to the support organization,
or is already known.
If the problem is a valid new one, an APAR may be raised, to be dealt with by the
CICS service team, as described in “APARs and fixes” on page 180. If, however,
the problem is already known, and a fix has been developed, you can obtain it as
described in “Obtaining the fix” on page 180.
Documenting problems
In a communication environment, where many clients may be connected to several
servers, you must obtain information from both the client and the server sides.
To facilitate problem determination, try to reduce your environment to only one
client workstation and one server to narrow down the range of possibilities that
may cause the error.
Listed below are the types of information most likely to be needed by the support
organization. The list is not exhaustive; it covers the most commonly requested
information.
v The version of the CICS Transaction Gateway, including details of any service
releases applied.
v The utility or programming language that gives the problem, for example:
– ECI, EPI, ESI
– C, C++
– Java
For languages, include the version.
v The network protocols being used.
v The end-to-end configuration, and product stacks at each step of the way, for
example, WebSphere Application Server async ECIRequest class over SSL to
ctgstart on Solaris up using TCP62 to CICS Transaction Server 2.2.
v The operating system on which the problem occurs. If the Client application and
CICS Transaction Gateway are on different operating systems, provide details of
both. Details of the CICS server are also useful.
178 CICS Transaction Gateway: UNIX and Linux Administration

v A minimum recreate scenario, if possible.
v Details of any log messages at the time the problem occurred.
v A short description of the problem in terms of CICS Transaction Gateway calls,
including why you think it is a problem with the CICS Transaction Gateway. For
example, a specific API call hangs and never returns, or an unexpected return
code on a specific API call.
Locating and compiling information
The advice listed below will help you compile the information required. If you are
in any doubt about how to gather any of the items listed above, wait until you can
seek advice from your support organization.
v Try to establish which program in your system seems to be the cause of the
problem. As you are reading this book, it is likely that you already believe the
CICS Transaction Gateway to be the problem source.
You also need to provide the version and release number of the product, for
example Version 7.0, together with the number of any PTF or other fix applied,
for example UNnnnnn (where nnnnn is a valid PTF number).
v You should find details of your compiler level on the product media labels or
the associated documentation. Alternatively, check the panel displayed on the
screen at compile time.
v Give the problem a severity level. Severity levels have the following meanings:
– Severity level 1 indicates that you are unable to use a program, resulting in a
critical condition that needs immediate attention.
– Severity level 2 indicates that you are able to use the program, but that
operation is severely restricted.
– Severity level 3 indicates that you are able to use the program, with limited
functions, but the problem is not critical to your overall operation.
– Severity level 4 indicates that you are able to use the program with the
problem causing negligible hindrance.
v Also, try to classify the error and give a brief description of the problem. Include
keywords associated with the problem, such as ABEND, WAIT, LOOP,
PERFORMANCE, INCORROUT, and MESSAGE, corresponding to the problem
classification types used in the RETAIN database. Strings containing other
keywords are also useful. These are not predefined, and might include such
items as a message or message number, an abend code, any parameters known
to be associated with the problem, or, for example, STARTUP, INITIALIZATION,
or TRANSIENT DATA.
v Finally, you should include your address, relevant contact names, and details of
the other products at your installation.
Keep a copy of the problem reporting sheet which summarizes all the information
relevant to the problem, together with any available documentation such as
dumps, traces and output from programs, translators, and compilers.
Submitting the documentation
If you are asked to provide documentation, it will help the support organization
during their investigation if you adhere to the following rules when preparing it:
v Provide as much information as possible in softcopy format.
v Write any notes and documents in English.
v If you are asked to supply any additional trace output, provide an unformatted
binary version, rather than the viewable output from the formatter.
Chapter 13. Problem determination and problem solving 179

v If you upload files to a mainframe system, do so in binary rather than ASCII
format.
APARs and fixes
After a reported problem is confirmed as being both new and valid, an authorized
program analysis report (APAR) is raised from the Problem Management Record
(PMR) and becomes a permanent record describing your error, and its solution. An
APAR is the means of reporting to the appropriate product service team any
problems you find with an IBM program.
The APAR process
The first step in the APAR process is that a Level-2 representative from the support
organization enters an APAR containing a description of your problem into the
RETAIN system. If you have a means of getting round the problem, details of this
are entered as well. Your name is also entered, so that your support organization
knows who to contact if the service team need to ask anything further about the
APAR documentation.
At this stage, you are given an APAR number. This number is always associated
with the APAR and its resolution and, if a code change is required, is associated
with the fix as well.
The service team may ask for additional backup documentation, normally via the
Level-2 representative. The specific documentation required will vary from
problem to problem, and depends on what information has already been supplied
during the PMR stage.
During the investigation, you can ask your support organization at any time about
how your APAR is progressing, particularly if it is a problem of high severity.
Obtaining the fix
When the service team has found a fix for your problem, you may be asked to test
it on your system. If so, you may be sent a Program Temporary Fix (PTF) in the
form of individual replacement modules. This is normally done through the
Level-2 organization and feedback from your testing will be requested.
Each PTF may contain several APAR fixes. If an individual APAR fix within a PTF
is found to be in error, it may still be advisable to apply the PTF, to obtain the
other APAR fixes.
In time, formal corrective service software is made available, which you can order
through your support organization. Traditionally, corrective service software has
been supplied on Corrective Service Diskettes (CSD) ordered by CSD number. It
may now be supplied on CD-ROM or via the Internet.
Fixes for CICS Transaction Gateway are available from the CICS Support web page
at:
www.ibm.com/software/ts/cics/support/
180 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Chapter 14. Migration
Migrating to Version 7
This information deals with issues that can arise when you move from an earlier
version of the CICS Transaction Gateway, or a product related to the CICS
Transaction Gateway.
This topic describes any special action you need to take if migrating from an
earlier version of the product.
Installation location
If you are upgrading from Version 5 or Version 6, the product is installed into your
existing directory structure, replacing the older version.
Terminal Servlet
The Terminal Servlet is no longer supported; use instead a CICS 3270 bridge
solution, or an IBM Host Integration solution.
Support for mixed case passwords
CICS Transaction Server for z/OS version 2.2 and higher supports mixed-case
passwords. To use mixed-case passwords, ensure that the “Use upper case
security” on page 72 field in the Configuration Tool is cleared.
Removal of configuration setting sotimeout
The sotimeout setting in the configuration file was deprecated at V6.0 of the CICS
TG, and is now not supported. If your configuration file contains an entry for
sotimeout, the Gateway daemon issues a warning message, and continues to start.
To suppress the message in future, remove any reference to sotimeout from the
configuration file. Open the configuration file in the Configuration Tool and then
save it.
Information log
Some Client information messages are now logged. You can configure a separate
log for information messages; see “Changing settings for Client daemon logging”
on page 69.
Migration considerations at Version 6
This information applies if you are migrating from Version 5 to Version 7.0.
HTTP and HTTPS protocols
Support for the HTTP and HTTPS protocols was removed in version 6. Use one of
these protocols instead:
© Copyright IBM Corp. 1996, 2006 181

Protocol Comments
TCP Use this in place of HTTP. See “TCP protocol settings” on page 60
for configuration details.
SSL Use this in place of HTTPS. See “SSL protocol settings” on page 62
for configuration details.
Supported ECI and EPI versions
Applications can be built only with the following ECI and EPI versions:
ECI_VERSION_1A
CICS_EPI_VERSION_200
Existing applications built with the following versions are still supported at run
time:
CICS_EPI_VERSION_100
CICS_EPI_VERSION_101
ECI_VERSION_1
Recompiling these applications will give a compiler error.
Configuration file: change of default name
The default configuration file is ctg.ini. In versions of the product before version 6
it was CTG.INI. The CICS Transaction Gateway accepts either ctg.ini or CTG.INI. If
both files are present the lowercase version is used; take one of the following steps:
v Specify the configuration file to be used; see “Using the Configuration Tool” on
page 50 for information on how to do this.
v Delete file CTG.INI.
If you have specified the configuration file, for example by setting the CICSCLI
environment variable, the exact file name specified is used.
User exits: change of file name
The user exits are now lower case:
Old name New name
CICSEPIX cicsepix
CICSEPIX cicsepix
The CICS Transaction Gateway first looks for a lower case exit, and then for an
upper case exit. If the objects are not found, no exit processing occurs.
Linux C++ applications
Recompile any applications that have been compiled with GNU C/C++ compiler
(gcc) 2.96 with a supported compiler; see “Supported software” on page 19 for
supported compilers.
Deprecated features
The following features are deprecated:
v Disabling the validation of units of work (Configuration Tool field “Validate
Units of Work” on page 55.)
182 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
v Disabling the validation of message qualifiers (Configuration Tool field
“Validate message qualifiers” on page 55.)
v Allowing Java Client applications to obtain generic replies (Configuration Tool
field “Let Java Clients obtain generic ECI replies” on page 55.)
v The Handler wakeup timeout (ms) field in the Configuration Tool. This setting
has been made redundant by the shutdown commands introduced with Version
6. A value of 0 in the configuration file is changed to 1000 by the Gateway
daemon; all other values are maintained for backwards compatibility. The field
has been removed from the Configuration Tool, and the Configuration Tool
ignores this setting if it is present in the configuration file.
Migration: support for resource adapters
The CICS Transaction Gateway supports communication with CICS TG resource
adapters of the same level, or an earlier level. For example:
v Using CICS TG V6.1 with resource adapters from V6.1, V6.0, and V5 is
supported.
v Using CICS TG V6.0 with V6.1 resource adapters is not supported.
Do not mix the levels of CICS TG resource adapters deployed on a WebSphere
Application Server node. For example, do not deploy a resource adapter from CICS
TG V6.1 to a node that has a V6.0 ECI or EPI resource adapter deployed. The
resource adapter version is shown in file ra.xml, in the resource adapter.
Migrating from CICS Transaction Gateway Version 4 and earlier
Migration from Version 4 and earlier is not supported. Uninstall the earlier version
before installing this version. The directory to which the product is installed will
change; see “Installation path” on page viii for details.
Chapter 14. Migration 183

184 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Chapter 15. Statistics introduction
This information introduces the statistics that are available from the CICS
Transaction Gateway.
Statistics can help with problem determination and capacity planning, and make it
possible to gain a snapshot of the current activity within the CICS Transaction
Gateway. The collection of statistics has an insignificant impact on performance,
and statistics are always available.
v Statistics can be collected by ctgadmin or the statistical API.
v Statistics apply only to the Gateway daemon that they were collected from.
v Statistical data is based on Java Client applications that run in remote mode; no
data is collected from applications that run in local mode.
Statistical resource groups
Which statistics do I need?
Every statistic belongs to a resource group. A resource group is a logical grouping of
resources such as connection managers. It defines an area for which statistical data
can be associated and retrieved.
This topic classifies statistics into different categories, according to how they are
most likely to be used. Some statistics appear in more than one category.
Statistics for tuning and capacity planning
These are some key statistics to look at when analyzing the performance of the
CICS TG.
It is recommended that a set of statistics is captured when the CICS TG is
operating under a number of different operating conditions in order to best
appreciate any changes that may subsequently take place and affect the
performance of the system.
CM_CALLOC
The current number of connection manager threads allocated to Java clients.
CM_CCURR
The current number of connection manager threads created. If this value is
greater than the configuration parameter initconnect, it signifies the peak
number of remote clients connected at any one time. This value will not exceed
the maximum number of connection managers defined in CM_SMAX.
CM_CWAITING
The current number of connection managers waiting for a worker thread to
become available. This statistic shows the number of requests that are queuing
in the Gateway daemon. It should usually be low or zero in a well-tuned
Gateway daemon. If it is higher than expected, consider increasing the
maxworker configuration parameter.
CM_LTIMEOUTS
The number of times that the Gateway daemon failed to allocate a connection
manager to a Java client application. This statistic shows the number of
© Copyright IBM Corp. 1996, 2006 185

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
incoming connection requests that have been refused. It should usually be low
or zero in a well-tuned Gateway daemon. If it is high, consider increasing the
connecttimeout or maxconnect configuration parameters.
CM_SMAX
The maximum number of connection manager threads that can possibly be
created and allocated by the Gateway daemon. It is defined by the
configuration file parameter maxconnect. This value limits the number of Java
clients that can be connected at any one time.
WT_CALLOC
The current number of worker threads that are being used by connection
managers. Another way of viewing this is the number of worker threads
processing requests. If this value is close to WT_SMAX, consider increasing the
maxworker configuration parameter.
WT_CCURR
The current number of worker threads created. If this value is greater than the
configuration parameter initworker, it signifies the peak number of parallel
requests that have been in process at any one time. This value will not exceed
the maximum number of worker threads defined in WT_SMAX.
WT_LTIMEOUTS
The number of times the Gateway daemon failed to allocate a worker thread to
a connection manager. This number signifies that requests are timing out
whilst queueing in the Gateway daemon. It should usually be low or zero in a
well-tuned Gateway daemon. If it is higher than expected, consider increasing
the maxworker or workertimeout configuration parameters.
WT_SMAX
The maximum number of parallel requests that the CICS Transaction Gateway
can process. It is defined by the configuration parameter maxworker.
Statistics to diagnose system problems
These are some key statistics to look at when diagnosing system problems.
CM_LTIMEOUTS
The number of times that the Gateway daemon failed to allocate a connection
manager to a Java client application.
WT_LTIMEOUTS
The number of times the Gateway daemon failed to allocate a worker thread to
a connection manager.
Statistics on resource usage
These are some key statistics to look at when considering the resources used by
your system.
CM_CALLOC
The current number of connection manager threads allocated to Java clients.
CM_CCURR
The current number of connection manager threads created. If this value is
greater than the configuration parameter initconnect, it signifies the peak
number of remote clients connected at any one time. This value will not exceed
the maximum number of connection managers defined in CM_SMAX.
WT_CALLOC
The current number of worker threads that are being used by connection
186 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
managers. Another way of viewing this is the number of worker threads
processing requests. If this value is close to WT_SMAX, consider increasing the
maxworker configuration parameter.
WT_CCURR
The current number of worker threads created. If this value is greater than the
configuration parameter initworker, it signifies the peak number of parallel
requests that have been in process at any one time. This value will not exceed
the maximum number of worker threads defined in WT_SMAX.
Statistics for throughput analysis
These are some key statistics to look at when considering transaction throughput
through the Gateway daemon.
GD_LALLREQ
The number of API calls (ECI, EPI, ESI), and XA requests that have been
processed. Failed and successful requests are included. Administrative requests
and handshakes are excluded.
GD_LLUWTXNC
The number of extended LUW based transactions that were committed. This
statistic returns information about one-phase-commit transactions.
GD_LLUWTXNR
The number of extended LUW based transactions that were rolled back. This
statistic returns information about one-phase-commit transactions.
GD_LRUNTIME
The length of time in seconds since the Gateway daemon successfully
initialized.
GD_LSYNCTXN
The number of synconreturn-based transactions (synconreturn ECI requests)
that were successfully completed.
Setting up your system for statistics
Displaying statistics
This information describes how to configure your system to deal with requests for
statistics.
Run the Configuration Tool and navigate to the Resources tab of the Gateway
daemon node.
1. Clear the Disabled check box.
2. Optional: enter a value in the Statistics API port if the default setting is not
suitable.
3. Save the configuration file and then stop and restart the Gateway daemon.
Related reference
“Statistics API port” on page 57
The Statistics API port allows the Gateway daemon to handle incoming
requests for the Statistics API.
Use ctgadmin to display statistical information about the CICS Transaction
Gateway.
Chapter 15. Statistics introduction 187

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Use the statistical options listed at “Statistical options” on page 129 to display
statistical information. Do not combine options.
Enter a command like the following at the command line:
ctgadmin -a stats options
For example, to display all available statistics about the CICS Transaction Gateway,
enter the following command:
ctgadmin -a stats -gs
The command is not case-sensitive.
Related reference
“Statistical options” on page 129
These options are available for use with the ctgadmin -a stats command.
Displaying all available statistics
Use ctgadmin together with the -gs option, to display all available statistical
information about the CICS Transaction Gateway.
Use the -gs option with no parameters, to display all available statistics.
Enter the following command:
ctgadmin -a stats -gs
Selecting the statistics to display
Use ctgadmin, together with the -gs option followed by a list of IDs, to display
statistics for one or more statistical IDs and resource groups.
Use the -gs option, followed by a list IDs for the statistics or resource groups.
Separate each item in the list by a colon (:).
For example, to display information about the worker thread resource group, the
maximum number of connection managers, and the Gateway daemon resource
group, enter the following command:
ctgadmin -a stats -gs wt:cm_smax:gd
Listing available resource groups
Use ctgadmin, together with the -rg parameter, to list available resource groups.
Use the -rg parameter, with no other options.
To list available resource groups, enter the following command:
ctgadmin -a stats -rg
Listing all available statistical IDs
Use ctgadmin, together with the -si parameter, to list available statistical IDs.
To list all available statistical IDs, enter the following command:
188 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ctgadmin -a stats -si
Listing statistical IDs for selected resource groups
Use ctgadmin, together with the -si parameter followed by a list IDs, to list
available statistical IDs.
To list statistical IDs for one or more resource groups, use the -si parameter
followed by a colon-separated list of resource groups. For example, to list statistical
IDs for the connection manager and worker thread resource groups, enter the
following command:
ctgadmin -a stats -si cm:wt
Getting help on statistics
Use ctgadmin -a stats -? to get help on statistics.
Resource groups
Issue the following command:
ctgadmin -a stats -?
This information describes the resource groups that are available from the CICS
Transaction Gateway.
A resource group is a logical grouping of resources such as connection managers. It
defines an area for which statistical data can be associated and retrieved. Each
resource group has these characteristics:
ID A unique identifier for the resource group. The ID is used by ctgadmin and the
statistical API to retrieve statistics, and is not case-sensitive.
Name
The name of the resource group, displayed when ctgadmin is used to display
statistical information.
Description
A description of the resource group.
These resource groups are defined:
Table 7. Resource groups
ID Name Description
cm connection manager Statistics about connection manager threads.
gd Gateway daemon Statistics on transaction counts, request counts, and Gateway status.
ph protocol handler Statistics about protocol handlers.
wt worker thread Statistics about worker threads.
List of statistics
This information describes the statistics that are available from the CICS
Transaction Gateway.
Each statistic has the following characteristics:
Chapter 15. Statistics introduction 189

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ID A unique identifier for the statistic. The ID is used by ctgadmin and the
statistical API to retrieve statistics, and is not case-sensitive. The structure of
the ID is as follows:
_
Each part of the ID is mandatory; their characteristics are as follows:
An alphanumeric string of one or more characters representing the
resource group that the statistic belongs to.
A single character; valid values are C, L, and S.
C Current: the statistic is based on a current evaluation; the value
is dynamic.
L Lifetime: the statistic is based on observations since the
Gateway daemon started; the value is dynamic. Each lifetime
statistic has a default value which is set when the Gateway
daemon is initialized.
S Startup: the statistic is based on a configuration setting for the
Gateway daemon; the value is static.
An alphanumeric string of one or more characters representing the
resource that information is being returned about.
Short description
The short description is displayed when ctgadmin is used to display statistical
information.
Description
A description of the information returned by the statistic.
Value returned
The type of information returned by the statistics:
Integer
The string value represents a 4-byte numeric value.
Long The string value represents an 8-byte numeric value.
String The string value represents character data.
These statistics are defined:
Connection manager statistics
These statistics belong to the connection manager resource group.
Table 8. Connection manager statistics
ID Short description Description Value returned
cm_calloc Currently allocated connection The current number of connection Integer
managers
manager threads allocated to Java
clients.
cm_ccurr Current number of connection The current number of connection Integer
managers
manager threads created.
190 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 8. Connection manager statistics (continued)
ID Short description Description Value returned
cm_cwaiting Number of connection
managers waiting
cm_ltimeouts Number of times
connecttimeout limit hit
cm_sinit Initial number of connection
managers
cm_smax Maximum number of
connection managers
The current number of connection
managers waiting for a worker thread
to become available.
The number of times that the Gateway
daemon failed to allocate a connection
manager to a Java client application.
The initial number of connection
manager threads created by the
Gateway daemon. It is defined by the
configuration file parameter
initconnect.
The maximum number of connection
manager threads that can possibly be
created and allocated by the Gateway
daemon. It is defined by the
configuration file parameter
maxconnect.
Gateway daemon statistics
These statistics belong to the Gateway daemon resource group.
Table 9. Gateway daemon statistics
Integer
Integer
Integer
Integer
Note: A value
of -1 indicates
no limit.
ID Short description Description Value returned
gd_cstatus Gateway daemon status Returns the status of the Gateway
daemon. Status is one of the
following: STARTING, RUNNING,
SHUTTING DOWN.
gd_lallreq Number of requests processed The number of API calls (ECI, EPI,
ESI), and XA requests that have been
processed. Failed and successful
requests are included. Administrative
requests and handshakes are excluded.
gd_lluwtxnc Extended LUW transactions
committed
gd_lluwtxnr Extended LUW transactions
rolled back
The number of extended LUW based
transactions that were committed. This
statistic returns information about
one-phase-commit transactions.
The number of extended LUW based
transactions that were rolled back.
This statistic returns information
about one-phase-commit transactions.
gd_lruntime Gateway daemon running time The length of time in seconds since
the Gateway daemon successfully
initialized.
gd_lsynctxn Successful SYNCONRETURN
transactions
The number of synconreturn-based
transactions (synconreturn ECI
requests) that were successfully
completed.
gd_sver CICS TG version The version of the CICS Transaction
Gateway.
String
Integer
Integer
Integer
Long
Integer
String
Chapter 15. Statistics introduction 191

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Protocol handler statistics
These statistics belong to the Gateway daemon resource group.
Table 10. Protocol handler statistics
ID Short description Description Value returned
ph_sportssl SSL protocol handler port
number
ph_sporttcp TCP protocol handler port
number
The SSL protocol handler port
number, or -1 if the protocol is not
enabled.
The TCP protocol handler port
number, or -1 if the protocol is not
enabled.
Worker thread statistics
These statistics belong to the worker thread resource group.
Table 11. Worker thread statistics
Integer
Integer
ID Short description Description Value returned
wt_calloc Currently allocated worker
threads
wt_ccurr Current number of worker
threads
wt_ltimeouts Number of times
workertimeout limit hit
wt_ltimeouts Initial number of worker
threads
wt_smax Maximum number of worker
threads
192 CICS Transaction Gateway: UNIX and Linux Administration
The current number of worker threads
that are being used by connection
managers. Another way of viewing
this is the number of worker threads
processing requests.
The current number of worker threads
created.
The number of times the Gateway
daemon failed to allocate a worker
thread to a connection manager.
The initial number of worker threads
created by the Gateway daemon. It is
defined by the configuration file
parameter initworker.
The maximum number of parallel
requests that the CICS Transaction
Gateway can process. It is defined by
the configuration parameter
maxworker.
Integer
Integer
Integer
Integer
Integer
Note: A value
of -1 indicates
no limit.

Appendix A. Data conversion when using the Client daemon
and a CICS server
Supported conversions
The ECI and EPI allow non-CICS applications running in a client system to gain
access to CICS facilities and data managed by a CICS server system.
Character data may have to be converted as it is passed between client and server;
for example data is encoded in ASCII on a client system and in EBCDIC on a CICS
mainframe server system. Data conversion is performed by the server system.
The possible ASCII and EBCDIC encoding schemes are described in detail in
SC09-2190, the Character Data Representation Architecture Reference and Registry
(CRDA). In summary, each encoding scheme is identified by a Coded Character Set
Identifier (CCSID) which defines a set of graphic characters and the Code Page
Global Identifier (CPGID) which specifies the code points used to represent the
graphic characters.
The data managed by the server system may be accessed from several client
systems each of which uses a different ASCII encoding scheme. To support such
access, each client system must be able to supply a CCSID ’tag’ in order that the
data is converted correctly.
The method used to perform data conversion depends on the server platform. The
range of data conversions supported also depends on the platform. The following
information is taken from Communicating from CICS on System/390, and is provided
as a guide; check the current copy of the book for full information. ASCII and
EBCDIC CCSIDs are assigned to geographic or linguistic groups.
Data conversion is supported between ASCII and EBCDIC where both CCSIDs
belong to the same group. The groups are:
Arabic
Baltic Rim
Latvia, Lithuania
Cyrillic
Eastern Europe: Bulgaria, Russia, Yugoslavia
Estonian
Estonia
Greek
Greece
Hebrew
Israel
Japanese
Japan
Korean
Korea
© Copyright IBM Corp. 1996, 2006 193

Arabic
Latin-1 and Latin-9
USA, Western Europe, and many other countries
Latin-2
Eastern Europe: Albania, Czech Republic, Hungary, Poland, Romania, Slovakia,
Yugoslavia, Former Yugoslavia
Latin-5
Turkey
Simplified Chinese
People’s Republic of China
Traditional Chinese
Taiwan
Vietnamese
Vietnam
The following tables list the CCSIDs supported for each group. For each CCSID,
they show:
v The value to be specified for the CLINTCP or SRVERCP keyword.
v The code page identifier or identifiers (CPGIDs).
v The current CICS on System/390 products that support the CCSID. Three levels
of support are defined—“Base”, “T01”, and “T02”.
Base
Table 12. Arabic, Client CCSIDs
– CICS Transaction Server for z/OS
– CICS Transaction Server for OS/390 (all releases)
– CICS/ESA ®
Version 4 Release 1
– CICS/VSE
– CICS/VSE Version 2 Release 3
T01
– CICS Transaction Server for z/OS
– CICS Transaction Server for OS/390 Release 3
– CICS Transaction Server for OS/390 Release 1 or Release 2 plus APAR
PQ19018
– CICS/ESA Version 4 Release 1 plus APAR PQ18896
– CICS/VSE
– CICS/VSE Version 2 Release 3 plus APAR PQ19019
T02
– CICS Transaction Server for z/OS
CLINTCP in CCSID CPGID Comments
864 Base 00864 00864 PC data: Arabic
1089
8859-6
Base 01089 01089 ISO 8859-6: Arabic
1256 T01 01256 01256 MS Windows: Arabic
194 CICS Transaction Gateway: UNIX and Linux Administration

Table 12. Arabic, Client CCSIDs (continued)
CLINTCP in CCSID CPGID Comments
5352 T02 05352 05352 MS Windows: Arabic, version 2 with euro
17248 T02 17248 00864 PC Data: Arabic with euro
Table 13. Arabic, Server CCSIDs
SRVERCP in CCSID CPGID Comments
420 Base 00420 00420 Host: Arabic
16804 T02 16804 00420 Host: Arabic with euro
Baltic Rim
Table 14. Baltic Rim, Client CCSIDs
Note: Data conversion does not change the direction of Arabic data.
CLINTCP in CCSID CPGID Comments
901 T02 00901 00901 PC data: Latvia, Lithuania; with euro
921 T01 00921 00921 PC data: Latvia, Lithuania
1257 T01 01257 01257 MS Windows: Baltic Rim
5353 T02 05353 05353 MS Windows: Baltic Rim, version 2 with euro
Table 15. Baltic Rim, Server CCSIDs
SRVERCP in CCSID CPGID Comments
1112 T01 01112 01112 Host: Latvia, Lithuania
1156 T02 01156 01156 Host: Latvia, Lithuania; with euro
Cyrillic
Table 16. Cyrillic, Client CCSIDs
CLINTCP in CCSID CPGID Comments
808 T02 00808 00808 PC data: Cyrillic, Russia; with euro
848 T02 00848 00848 PC data: Cyrillic, Ukraine; with euro
849 T02 00849 00849 PC data: Cyrillic, Belarus; with euro
855 Base 01235 00855 PC data: Cyrillic
866 Base 00866 00866 PC data: Cyrillic, Russia
872 T02 00872 00872 PC data: Cyrillic with euro
915
8859-5
Base 00915 00915 ISO 8859-5: Cyrillic
1124 T02 01124 01124 8-bit: Cyrillic, Belarus
1125 T02 01125 01125 PC Data: Cyrillic, Ukraine
1131 T02 01131 01131 PC Data: Cyrillic, Belarus
1251 T01 01251 01251 MS Windows: Cyrillic
5347 T02 05347 05347 MS Windows: Cyrillic, version 2 with euro
Appendix A. Data conversion when using the Client daemon and a CICS server 195

Table 17. Cyrillic, Server CCSIDs
SRVERCP in CCSID CPGID Comments
1025 Base 01025 01025 Host: Cyrillic multilingual
1123 T02 01123 01123 Host: Cyrillic Ukraine
1154 T02 01154 01154 Host: Cyrillic multilingual; with euro
1158 T02 01158 01158 Host: Cyrillic Ukraine; wtih euro
Estonian
Table 18. Estonian, Client CCSIDs
CLINTCP in CCSID CPGID Comments
902 T02 00902 00902 PC data: Estonia with euro
922 T01 00922 00922 PC data: Estonia
1257 T01 01257 01257 MS Windows: Baltic Rim
5353 T02 05353 05353 MS Windows: Baltic Rim, version2 with euro
Table 19. Estonian, Server CCSIDs
SRVERCP in CCSID CPGID Comments
1122 T01 01122 01122 Host: Estonia
1157 T01 01157 01157 Host: Estonia with euro
Greek
Table 20. Greek, Client CCSIDs
CLINTCP in CCSID CPGID Comments
813
8859-7
Base 00813 00813 ISO 8859-7: Greece
869 Base 00869 00869 PC data: Greece
1253 T01 01253 01253 MS Windows: Greece
4909 T02 04909 00813 ISO 8859-7: Greece with euro
5349 T02 05349 01253 MS Windows: Greece, version 2 with euro
9061 T02 09061 00869 PC Data: Greece with euro
Table 21. Greek, Server CCSIDs
SRVERCP in CCSID CPGID Comments
875 Base 00875 00875 Host: Greece
4971 T02 04971 00875 Host: Greece with euro
Hebrew
Table 22. Hebrew, Client CCSIDs
CLINTCP in CCSID CPGID Comments
856 Base 00856 00856 PC data: Hebrew
196 CICS Transaction Gateway: UNIX and Linux Administration

Table 22. Hebrew, Client CCSIDs (continued)
CLINTCP in CCSID CPGID Comments
862 T02 00862 00862 PC data: Hebrew (migration)
867 T02 00867 00867 PC Data: Hebrew with euro
916
8859-8
Base 00916 00916 ISO 8859-8: Hebrew
1255 T01 01255 01255 MS Windows: Hebrew
5351 T02 05351 05351 MS Windows: Hebrew, version 2 with euro
Table 23. Hebrew, Server CCSIDs
SRVERCP in CCSID CPGID Comments
424 Base 00424 00424 Host: Hebrew
803 T02 00803 00803 Host: Hebrew (Character Set A)
4899 T02 04899 00803 Host: Hebrew (Character Set A) with euro
12712 T02 12712 00424 Host: Hebrew with euro and new sheqel
Japanese
Table 24. Japanese, ASCII
Note: Data conversion does not change the direction of Hebrew data.
CLINTCP in CCSID CPGID Comments
932 Base 00932 1. 00897
2. 00301
942 Base 00942 1. 01041
2. 00301
943 T01 00943 1. 00897
2. 00941
954
EUCJP
Base 00954 1. 00895
2. 00952
3. 00896
4. 00953
5050 T02 05050 1. 00895
2. 00952
3. 00896
4. 00953
Table 25. Japanese, EBCDIC
SRVERCP CCSID CPGID Comments
930 Base 00930 1. 00290
2. 00300
3. 00290
4. 00300
1. PC data: SBCS
2. PC data: DBCS including 1880 user-defined
characters
1. PC data: Extended SBCS
2. PC data: DBCS including 1880 user-defined
characters
1. PC data: SBCS
2. PC data: DBCS for Open environment including
1880 IBM user-defined characters
1. G0: JIS X201 Roman
2. G1: JIS X208-1990
3. G1: JIS X201 Katakana
4. G1: JIS X212
1. G0: JIS X201 Roman
2. G1: JIS X208-1990
3. G1: JIS X201 Katakana
4. G1: JIS X212
1. Katakana Host: extended SBCS
2. Kanji Host: DBCS including 4370 user-defined
characters
3. Katakana Host: extended SBCS
4. Kanji Host: DBCS including 1880 user-defined
characters
Appendix A. Data conversion when using the Client daemon and a CICS server 197

Table 25. Japanese, EBCDIC (continued)
SRVERCP CCSID CPGID Comments
931 Base 00931 1. 00037
2. 00300
939 Base 00939 1. 01027
2. 00300
3. 01027
4. 00300
1390 T02 01390 1. 00290
2. 00300
1399 T02 01399 1. 01027
2. 00300
Korean
Table 26. Korean, ASCII
CLINTCP in CCSID CPGID Comments
934 Base 00934 1. 00891
2. 00926
944 Base 00944 1. 01040
2. 00926
949 Base 00949 1. 01088
2. 00951
970
EUCKR
Base 00970 1. 00367
2. 00971
1363 T01 01363 1. 01126
2. 01362
Table 27. Korean, EBCDIC
SRVERCP in CCSID CPGID Comments
933 Base 00933 1. 00833
2. 00834
1364 T02 01364 1. 00833
2. 00834
198 CICS Transaction Gateway: UNIX and Linux Administration
1. Latin Host: SBCS
2. Kanji Host: DBCS including 4370 user-defined
characters
1. Latin Host: extended SBCS
2. Kanji Host: DBCS including 4370 user-defined
characters
3. Latin Host: extended SBCS
4. Kanji Host: DBCS including 1880 user-defined
characters
1. Katakana Host: extended SBCS; with euro
2. Kanji Host: DBCS including 6205 user-defined
characters
1. Latin Host: extended SBCS; with euro
2. Kanji Host: DBCS including 4370 user-defined
characters; with euro
1. PC data: SBCS
2. PC data: DBCS including 1880 user-defined
characters
1. PC data: Extended SBCS
2. PC data: DBCS including 1880 user-defined
characters
1. IBM KS Code - PC data: SBCS
2. IBM KS code - PC data: DBCS including 1880
user-defined characters
1. G0: ASCII
2. G1: KSC X5601-1989 including 1880 user-defined
characters
1. PC data: MS Windows Korean SBCS
2. PC data: MS Windows Koran DBCS including
11172 full Hangul
1. Host: Extended SBCS
2. Host: DBCS including 1880 user-defined characters
and 11172 full Hangul characters
1. Host: Extended SBCS
2. Host: DBCS including 1880 user-defined characters
and 11172 full Hangul characters

Latin-1 and Latin-9
Table 28. Latin-1, Client CCSIDs
CLINTCP in CCSID CPGID Comments
437 Base 00437 00437 PC data: PC Base; USA, many other countries
819
8859-1
Base 00819 00819 ISO 8859-1: Latin-1 countries
850 Base 00850 00850 PC data: Latin-1 countries
858 T01 00858 00858 PC data: Latin-1 countries; with euro
923 T01 00923 00923 ISO 8859-15: Latin-9
924 T02 00924 00924 ISO 8859-15: Latin-9
1047 T02 01047 01047 Host: Open Edition Latin-1
1252 T01 01252 01252 MS Windows: Latin-1 countries
5348 T01 05348 01252 MS Windows: Latin-1 countries, version 2 with euro
Table 29. Latin-1 and Latin-9, Server CCSIDs
SRVERCP in CCSID CPGID Comments
037 Base 00037 00037 Host: USA, Canada (ESA), Netherlands, Portugal,
Brazil, Australia, New Zealand
273 Base 00273 00273 Host: Austria, Germany
277 Base 00277 00277 Host: Denmark, Norway
278 Base 00278 00278 Host: Finland, Sweden
280 Base 00280 00280 Host: Italy
284 Base 00284 00284 Host: Spain, Latin America (Spanish)
285 Base 00285 00285 Host: United Kingdom
297 Base 00297 00297 Host: France
500 Base 00500 00500 Host: Belgium, Canada (AS/400 ® ), Switzerland,
International Latin-1
871 Base 00871 00871 Host: Iceland
924 T01 00924 00924 Host: Latin-9
1047 T01 01047 01047 Host: Open Edition Latin-1
1140 T01 01140 01140 Host: USA, Canada (ESA), Netherlands, Portugal,
Brazil, Australia, New Zealand; with euro
1141 T01 01141 01141 Host: Austria, Germany; with euro
1142 T01 01142 01142 Host: Denmark, Norway; with euro
1143 T01 01143 01143 Host: Finland, Sweden; with euro
1144 T01 01144 01144 Host: Italy; with euro
1145 T01 01145 01145 Host: Spain, Latin America (Spanish); with euro
1146 T01 01146 01146 Host: United Kingdom; with euro
1147 T01 01147 01147 Host: France; with euro
1148 T01 01148 01148 Host: Belgium, Canada (AS/400), Switzerland,
International Latin-1; with euro
1149 T01 01149 01149 Host: Iceland; with euro
Appendix A. Data conversion when using the Client daemon and a CICS server 199

Latin-2
Table 30. Latin-2, ASCII
Note: Conversions are supported between non euro-supported CCSIDs and
euro-supported CCSIDs. These should be used with care because:
v The international currency symbol in each non euro-supported EBCDIC
CCSID (for example, 00500) has been replaced by the euro symbol in the
equivalent euro-supported EBCDIC CCSID (for example, 01148).
v The dotless i in non euro-supported ASCII CCSID 00850 has been
replaced by the euro symbol in the equivalent euro-supported ASCII
CCSID 00858.
CLINTCP in CCSID CPGID Comments
852 Base 00852 00852 PC data: Latin-2 multilingual
912
8859-2
Base 00912 00912 ISO 8859-2: Latin-2 multilingual
1250 T01 01250 01250 MS Windows: Latin-2
5346 T02 05346 01250 MS Windows: Latin-2, version 2 with euro
9044 T02 09044 00852 PC data: Latin-2 multilingual with euro
Table 31. Latin-2, Server CCSIDs
SRVERCP in CCSID CPGID Comments
500 T02 00500 00500 Host: International Latin-1
870 Base 00870 00870 Host: Latin-2 multilingual
1148 T02 01148 01148 Host: International Latin-1 with euro
1153 T02 01153 01153 Host: Latin-2 multilingual with euro
Latin-5
Table 32. Latin-5, Client CCSIDs
Note: Conversions are supported for some combinations of Latin-2 ASCII CCSIDs
and Latin-1 EBCDIC CCSIDs.
CLINTCP in CCSID CPGID Comments
857 Base 00857 00857 PC data: Latin-5 (Turkey)
920
8859-9
Base 00920 00920 ISO 8859-9: Latin-5 (ECMA-128, Turkey TS-5881)
1254 T01 01254 01254 MS Windows: Turkey
5350 T02 05350 01254 MS Windows: Turkey, version 2 with euro
9049 T02 09049 00857 PC data: Latin-5 (Turkey) with euro
Table 33. Latin-5, Server CCSIDs
SRVERCP in CCSID CPGID Comments
1026 Base 01026 01026 Host: Latin-5 (Turkey)
1155 T02 01155 01155 Host: Latin-5 (Turkey) with euro
200 CICS Transaction Gateway: UNIX and Linux Administration

Simplified Chinese
Table 34. Simplified Chinese, ASCII
CLINTCP in CCSID CPGID Comments
946 Base 00946 1. 01042
2. 00928
1381 Base 01381 1. 01115
2. 01380
1383
EUCCN
T01 01383 1. 00367
2. 01382
1386 T01 01386 1. 01114
2. 01385
Table 35. Simplified Chinese, EBCDIC
SRVERCP in CCSID CPGID Comments
935 Base 00935 1. 00836
2. 00837
1388 T02 01388 1. 00836
2. 00837
9127 T02 09127 1. 00836
2. 00837
Traditional Chinese
Table 36. Traditional Chinese, ASCII
CLINTCP in CCSID CPGID Comments
938 Base 00938 1. 00904
2. 00927
948 Base 00948 1. 01043
2. 00927
950
BIG5
964
EUCTW
Base 00950 1. 01114
2. 00947
Base 00964 1. 00367
2. 00960
3. 00961
1370 T02 01370 1. 01114
2. 00947
1. PC data: Extended SBCS
2. PC data: DBCS including 1880 user-defined
characters
1. PC data: Extended SBCS (IBM GB)
2. PC data: DBCS (IBM GB) including 31
IBM-selected, 1880 user-defined characters
1. G0: ASCII
2. G1: GB 2312-80 set
1. PC data: S-Chinese GBK and T-Chinese IBM BIG-5
2. PC data: S-Chinese GBK
1. Host: Extended SBCS
2. Host: DBCS including 1880 user-defined characters
1. Host: Extended SBCS
2. Host: DBCS including 1880 user-defined characters
1. Host: Extended SBCS
2. Host: DBCS including 1880 user-defined characters
1. PC data: SBCS
2. PC data: DBCS including 6204 user-defined
characters
1. PC data: Extended SBCS
2. PC data: DBCS including 6204 user-defined
characters
1. PC data: SBCS (IBM BIG5)
2. PC data: DBCS including 13493 CNS, 566 IBM
selected, 6204 user-defined characters
1. G0: ASCII
2. G1: CNS 11643 plane 1
3. G1: CNS 11643 plane 2
1. PC data: Extended SBCS; with euro
2. PC data: DBCS including 6204 user-defined
characters; with euro
Appendix A. Data conversion when using the Client daemon and a CICS server 201

Table 37. Traditional Chinese, EBCDIC
SRVERCP in CCSID CPGID Comments
937 Base 00937 1. 00037
2. 00835
1371 T02 01371 1. 01159
2. 00835
Vietnamese
Table 38. Vietnamese, Client CCSIDs
CLINTCP in CCSID CPGID Comments
1129 T02 01129 01129 ISO-8: Vietnamese
1. Host: Extended SBCS
2. Host: DBCS including 6204 user-defined characters
1. Host: Extended SBCS; with euro
2. Host: DBCS including 6204 user-defined characters;
with euro
1163 T02 01163 01163 ISO-8: Vietnamese with euro
1258 T02 01258 01258 MS Windows: Vietnamese
5354 T02 05354 01258 MS Windows: Vietnamese, version 2 with euro
Table 39. Vietnamese, Server CCSIDs
SRVERCP in CCSID CPGID Comments
1130 T02 01130 01130 Host: Vietnamese
1164 T02 01164 01164 Host: Vietnamese with euro
Table 40. Unicode
CLINTCP
SRVERCP
Unicode data
CICS on System/390 provides limited support for Unicode-encoded character data.
The support allows workstations to share UCS-2 or UTF-8 encoded data with the
System/390 provided, that no conversion is required.
in CCSID CPGID Comments
1200 UCS-2 T01 01200 01400 UCS-2 level 3, maximal (growing) character set
1208 UTF-8 T01 01200 01400 UTF-8 based on UCS-2 level 3, maximal (growing)
character set
13488 T01 13488 01400 UCS-2 level 1 (level 3 tolerant), subset (fixed) character
set
202 CICS Transaction Gateway: UNIX and Linux Administration

Appendix B. Editing the configuration file ctg.ini
ctg.ini: GATEWAY section
A sample configuration file is supplied: /bin/ctgsamp.ini. To create
a new configuration, copy this file to /bin/ctg.ini and edit the
copy.
The configuration file is a text file consisting of a number of sections. Each section
starts with SECTION as the first entry on a line, and ends with ENDSECTION.
This information maps entries in the configuration file to the corresponding fields
in the Configuration Tool. For an explanation of the fields see the Configuration
chapter in the Administration book.
If you use the number sign (#) character to denote a comment, either:
v place it at the start of a line; or
v precede it by a space or tab character
because some valid names (for example modename) can start with the # character.
Some lines of the INI file are longer than 72 characters; take care when editing
them.
There must be one GATEWAY section. Entries correspond to fields in the Gateway
daemon settings panel of the Configuration Tool:
Table 41. SECTION GATEWAY
Entry in the INI file Configuration Tool field
adminport “Port for local administration” on page 57
closetimeout “Timeout for in-progress requests to complete (ms)” on
page 56
ecigenericreplies “Let Java Clients obtain generic ECI replies” on page 55.
Set this to on to enable the field.
statsport “Statistics API port” on page 57
uowvalidation “Validate Units of Work” on page 55. Set this to on to
enable the field.
msgqualvalidation “Validate message qualifiers” on page 55. Set this to on
to enable the field.
connectionlogging “Log Java Client connections and disconnections” on
page 58. Set this to on to enable the field.
initconnect “Initial number of Connection Manager threads” on page
53
initworker “Initial number of Worker threads” on page 54
log@error.dest “Error and warning log destination” on page 58. Set this
to either console or file.
© Copyright IBM Corp. 1996, 2006 203

Table 41. SECTION GATEWAY (continued)
Entry in the INI file Configuration Tool field
log@error.parameters “Error log file name” on page 58, “Error log maximum
size (KB)” on page 58 and “Maximum number of
archived error log files” on page 58. These parameters
are used if the destination is file; entries take the
following form:
log@error.parameters=filename=filename;
filesize=filesize;
maxfiles=number
Parameter values can appear in any order separated by
semi-colons (;).
log@info.dest “Information log destination” on page 59. Set this to
either console or file.
log@info.parameters “Information log file name” on page 59, “Information log
maximum size (KB)” on page 59 and “Maximum number
of archived information log files” on page 59. These
parameters are used if the destination is file; entries take
the following form:
log@error.parameters=filename=filename;
filesize=filesize;
maxfiles=number
Parameter values can appear in any order separated by
semi-colons (;).
maxconnect “Maximum number of Connection Manager threads” on
page 54. Enter the number, or -1 for unrestricted.
maxworker “Maximum number of Worker threads” on page 54.
Enter the number, or -1 for unrestricted.
noinput “Enable reading input from console” on page 55. Set this
to off to enable the field.
nonames “Display TCP/IP hostnames” on page 57. Set this to off
to enable the field.
notime No equivalent field. Set this to on to disable timing
information in messages.
tfile “Gateway trace file” on page 80
trace Equivalent to Gateway under “Trace Settings” on page
79. Set this to on to enable Gateway trace, otherwise
omit.
workertimeout “Worker thread available timeout (ms)” on page 56
tfilesize “Gateway trace file wrap size (KB)” on page 80
Two lines are present in the configuration file for each protocol that is enabled.
Protocol settings take this form:
v The first line defines the protocol.
v The second line defines the parameters.
v Parameters are separated by a semicolon.
v If you will use the Configuration Tool, do not split long lines. If you do not
intend to use the Configuration Tool, you may split long lines by placing the
backslash character (\) after a semicolon, as shown:
204 CICS Transaction Gateway: UNIX and Linux Administration

Table 42. TCP protocol
protocol@tcp.parameters=connecttimeout=2000;\
idletimeout=600000;
Entries for each supported protocol follow.
TCP protocol
To enable the protocol, insert this line:
protocol@tcp.handler=com.ibm.ctg.server.TCPHandler
Follow it with a line like this:
protocol@tcp.parameters=bind=host.domain.org;connecttimeout=3;dropworking;\
idletimeout=4;pingfrequency=5;port=1;requiresecurity;\
solinger=6;
Entries correspond to fields in the TCP settings panel:
Entry in the INI file Configuration Tool field
bind “Bind Address” on page 60
connecttimeout “Connection timeout (ms)” on page 61
dropworking “Drop working connections” on page 62. Include this to
enable the field, otherwise omit.
idletimeout “Idle timeout (ms)” on page 61
pingfrequency “Ping time frequency (ms)” on page 61
port “Port” on page 61
requiresecurity “Require Java Clients to use security classes” on page 62.
Include this to enable the field, otherwise omit.
solinger “SO_LINGER setting” on page 62
Table 43. SSL protocol
SSL protocol
To enable the protocol, insert this line:
protocol@ssl.handler=com.ibm.ctg.server.SslHandler
Follow it with a line like this:
protocol@ssl.parameters=clientauth=on;connecttimeout=9;\
dropworking;idletimeout=10;keyring=Key ring or Keystore name;\
keyringpw=a2V5cmluZyBvciBLZXlzdG9yZSBwYXNzd29yZA==;keyringpwscrambled=on;\
pingfrequency=11;port=7;requiresecurity;solinger=12;\
ciphersuites=SSL_DH_anon_EXPORT_WITH_DES40_CBC_SHA,\
SSL_DH_anon_WITH_3DES_EDE_CBC_SHA;
Entries correspond to fields in the SSL settings panel:
Entry in the INI file Configuration Tool field
ciphersuites “Use only these ciphers” on page 64. To restrict the
cipher suites that can be used with the SSL protocol,
enter a comma-separated list of cipher suites. To allow
all available cipher suites to be used, omit the entry. Use
of the value 128bitonly is deprecated.
clientauth “Use client authentication” on page 63. Set this to on to
use client authentication, otherwise omit.
Appendix B. Editing the configuration file ctg.ini 205

|
Table 43. SSL protocol (continued)
Entry in the INI file Configuration Tool field
connecttimeout “Connection timeout (ms)” on page 61
dropworking “Drop working connections” on page 62. Include this to
enable the field, otherwise omit.
idletimeout “Idle timeout (ms)” on page 61
keyring “Key ring file” on page 63
keyringpw “Key ring password” on page 64. To encrypt this entry:
1. Ensure that keyringpwscrambled is set to on.
2. Save the configuration file.
3. Open and then save the file in the Configuration
Tool.
keyringpwscrambled No equivalent entry. Set this to on to scramble the “Key
ring password” on page 64.
pingfrequency “Ping time frequency (ms)” on page 61
port “Port” on page 61
requiresecurity “Require Java Clients to use security classes” on page 62.
Include this to enable the field, otherwise omit.
solinger “SO_LINGER setting” on page 62
ctg.ini: CLIENT section
Table 44. SECTION CLIENT
There must be one CLIENT section. Entries correspond to fields in the Client
Configuration and Trace settings panels of the Configuration Tool. The section
name also stores the value entered in the “Application ID” on page 65 field of the
Configuration Tool.
Entry in the INI file Configuration Tool field
SECTION CLIENT “Application ID” on page 65
CCSID “Code page identifier override” on page 68
CPNAME “Fully qualified CP name or template” on page 76
(under Common TCP62 settings)
CPIPADDRESSMASK “IP address mask for CP name (optional)” on page 77
(under Common TCP62 settings)
DOMAINNAMESUFFIX “AnyNet domain name suffix” on page 77 (under
Common TCP62 settings)
LOGFILE “Error and warning log file” on page 68
LOGFILEINFO “Information log file” on page 69
TCP62PORT “TCP62 port” on page 77 (under Common TCP62
settings)
MAXBUFFERSIZE “Maximum buffer size” on page 66
MAXREQUESTS “Maximum requests” on page 66
MAXSERVERS “Maximum servers” on page 66
MAXWRAPSIZE “Client trace file wrap size (KB)” on page 81
PRINTCOMMAND “Print command” on page 67
206 CICS Transaction Gateway: UNIX and Linux Administration

|
|
Table 44. SECTION CLIENT (continued)
Entry in the INI file Configuration Tool field
PRINTFILE “Print file” on page 67
REMOTENODEINACTIVITYPOLLINTERVAL “Remote node inactivity poll interval (s)” on page 78
(under Common TCP62 settings)
SRVRETRYINTERVAL “Server retry interval” on page 68
TERMINALEXIT “Terminal exit” on page 66
TERMINSTLOGGING “Log terminal installations and deinstallations” on page
68
TRACEFILE “Client trace file” on page 80
TRACE A comma-separated list of components to trace, as
entered on the “Trace Settings” on page 79 panel.
Possible entries are as follows:
ALL Trace everything
API Client API level 1
API.2 Client API level 2 (also traces level 1)
TRN Transport layer
DRV Protocol drivers level 1
DRV.2 Protocol drivers level 2 (also traces level 1)
CLI CICSCLI command line
CCL Client daemon
EMU CICSTERM and CICSPRINT
CPP CPP classes
ctg.ini: SERVER section
Table 45. SECTION SERVER
This section defines a server to which the Client daemon may connect. There may
be more than one SERVER section. The first server listed is the default. The section
name also stores the value entered in the Server name field of the Configuration
Tool.
Entry in the INI file Configuration Tool field
SECTION SERVER “Server name” on page 71
DESCRIPTION “Description” on page 71
INITIALTRANSID “Initial transaction” on page 71
MODELTERM “Model terminal definition” on page 71
UPPERCASESECURITY “Use upper case security” on page 72. Set to Y to enable,
otherwise set to N.
PROTOCOL Network protocol. Valid entries are SNA (AIX and Linux
on zSeries operating systems only), TCP62, TCPIP. The
Network protocol must correspond to an entry in the
DRIVER section; see “ctg.ini: DRIVER section” on page
208.
Other entries in this section depend upon the protocol selected.
Appendix B. Editing the configuration file ctg.ini 207

Table 46. SECTION SERVER: additional entries for the TCP protocol
Entry in the INI file Configuration Tool field
NETNAME “Hostname or IP address” on page 72
PORT “Port” on page 73
CONNECTTIMEOUT “Connection timeout” on page 73
SRVIDLETIMEOUT “Server idle timeout (mins)” on page 72
TCPKEEPALIVE “Send TCP/IP KeepAlive packets” on page 73. Set to Y
to enable, otherwise set to N.
Table 47. SECTION SERVER: additional entries for the TCP62 protocol
Entry in the INI file Configuration Tool field
LOCALLUNAME “Local LU name or template” on page 74
LUIPADDRESSMASK “IP address mask for LU name template (optional)” on
page 75
SNAMAXRUSIZE “Maximum SNA RU size” on page 78
SNASESSIONLIMIT “Maximum logical SNA sessions” on page 78
MODENAME “Mode name” on page 76
SNAPACINGSIZE “SNA pacing size” on page 78
NETNAME “Partner LU name” on page 74
Note:
1. Entries corresponding to the Common TCP62 settings panel on the
Configuration Tool are stored in the CLIENT section of the INI file; see
“ctg.ini: CLIENT section” on page 206
2. When configuring a TCP62 CICS server, you must also update the local
“Hosts file” on page 74; see the Configuration chapter in the
Administration book for details.
Table 48. SECTION SERVER: additional entries for the SNA protocol
Entry in the INI file Configuration Tool field
LOCALLUNAME “Local LU name” on page 74
MODENAME “Mode name” on page 76
NETNAME “Partner LU name” on page 74
SRVIDLETIMEOUT “Server idle timeout (mins)” on page 72
ctg.ini: DRIVER section
This section defines a communications protocol library used to communicate with
a server. There should be one DRIVER section for each Network protocol used
with your servers; see “ctg.ini: SERVER section” on page 207. Entries take the
following form:
SECTION DRIVER=
DRIVERNAME=
ENDSECTION
208 CICS Transaction Gateway: UNIX and Linux Administration

Table 49. DRIVER section
Valid entries for Corresponding
SNA CCLIBMSN
TCP62 CCLTCP62
TCPIP CCLIBMIP
The DRIVER section has no corresponding section in the Configuration Tool. The
Configuration Tool automatically selects the correct protocol drivers.
Appendix B. Editing the configuration file ctg.ini 209

210 CICS Transaction Gateway: UNIX and Linux Administration

The product library and related literature
This information lists books on the CICS Transaction Gateway, and related topics.
CICS Transaction Gateway books
v CICS Transaction Gateway: Windows Administration, SC34-6371
This book describes the administration of the CICS Transaction Gateway for
Windows.
v CICS Transaction Gateway: UNIX and Linux Administration, SC34-6372
This book describes the administration of the CICS Transaction Gateway for
UNIX and Linux.
v CICS Transaction Gateway: z/OS Administration, SC34-6672
This book describes the administration of the CICS Transaction Gateway for
z/OS.
v CICS Transaction Gateway: Messages, SC34-6675
This online book lists and explains the error messages that can be generated by
the CICS Transaction Gateway.
v CICS Transaction Gateway: Programming Reference, SC34-6674
This book provides information on the APIs of the programming languages
supported by the CICS Transaction Gateway.
Additional HTML pages contain JAVA programming reference information.
v CICS Transaction Gateway: Programming Guide, SC34-6673
This introduction to programming for the CICS Transaction Gateway provides
the information that you need to allow user applications to use CICS facilities in
a client/server environment.
Sample configuration documents
Redbooks
Several sample configuration documents are available in portable document format
(PDF). These documents give step-by-step guidance for configuring CICS
Transaction Gateway for communication with CICS servers, using various
protocols. They provide detailed instructions that extend the information in the
CICS Transaction Gateway library.
Visit the following Web site:
www.ibm.com/software/cics/ctg
and follow the Library link.
The following International Technical Support Organization (ITSO) Redbook
publication contains many examples of client/server configurations:
v CICS Transaction Gateway V5 - The WebSphere Connector for CICS, SG24-6133
v Revealed! Architecting Web Access to CICS, SG24-5466
v Enterprise JavaBeans
for z/OS and OS/390 CICS Transaction Server V2.2, SG24-6284
v Java Connectors for CICS: Featuring the J2EE Connector Architecture, SG24-6401.
This book provides information on developing J2EE applications.
© Copyright IBM Corp. 1996, 2006 211

Other Useful Books
v Systems Programmer’s Guide to Resource Recovery Services (RRS), SG24-6980-00.
This book provides information on using RRS in various scenarios.
v Communications Server for z/OS V1R2 TCP/IP Implementation Guide, SG24-6517-00.
This book provides information on using Communications Server for z/OS
V1R2, including load balancing.
v Redpaper: Transactions in J2EE, REDP-3659-00. This redpaper provides a
discussion of transactions in the J2EE environment, including one- and XA
transactions.
You can obtain ITSO Redbooks
from a number of sources. For the latest
information, see:
www.ibm.com/redbooks/
CICS Transaction Server publications
CICS Transaction Server for z/OS RACF Security Guide, SC34-6249
CICS interproduct communication
The following books describe the intercommunication facilities of the CICS server
products:
v CICS Family: Interproduct Communication, SC34-6267
v CICS Transaction Server for Windows V5.0 Intercommunication, SC34-6209
v CICS Transaction Server for z/OS CICS External Interfaces Guide, SC34-6449
v CICS Transaction Server for z/OS: Intercommunication Guide, SC34-6448
v CICS/VSE 2.3: Intercommunication Guide, SC33-0701
v CICS Transaction Server for iSeries V5R2: Intercommunication, SC41-5456
v TXSeries 5.1: CICS Intercommunication Guide, SC09-4462
The first book above is a CICS family book containing a platform-independent
overview of CICS interproduct communication.
CICS problem determination books
The following books describe the problem determination facilities of the CICS
server products:
v Transaction Server for Windows V5.0: Problem Determination, GC34-6210
v CICS Transaction Server for z/OS V3.1 CICS Problem Determination Guide,
SC34-6441
v CICS/VSE 2.3 Problem Determination Guide, SC33-0716
v CICS Transaction Server for iSeries V5R2: Problem Determination, SC41-5453
v TXSeries V5.1: CICS Problem Determination Guide, SC09-4465
You can find information on CICS products at the following Web site:
www.ibm.com/software/cics/ctg
212 CICS Transaction Gateway: UNIX and Linux Administration

APPC-related publications
IBM products
IBM Communications Server
See this Web page:
www.ibm.com/software/network/commserver/library
IBM Personal Communications
See this Web page:
www.ibm.com/software/network/pcomm/library
Systems Network Architecture (SNA)
v SNA Formats, GA27-3136
v Systems Network Architecture Technical Overview, GC30-3073
v Guide to SNA over TCP/IP, SC31-6527
TCP62–related publications
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
GC31–7073
Obtaining books from IBM
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074
For information on books you can download, visit our Web site at:
www.ibm.com/software/cics/ctg
and follow the Library link.
The product library and related literature 213

214 CICS Transaction Gateway: UNIX and Linux Administration

Accessibility features for CICS Transaction Gateway
Installation
Documentation
Accessibility features help users who have a physical disability, such as restricted
mobility or limited vision, to use information technology products successfully. The
CICS Transaction Gateway supports keyboard-only operation. Topics on the
following pages give details of accessibility features.
Visit the IBM Accessibility Center for more information about IBM’s commitment
to accessibility.
The InstallShield wizard is not fully accessible to screen readers. An alternative is
to use the -console option; see “Installing from the console” on page 30.
See the Eclipse information center for an HTML version of the documentation.
Configuration Tool accessibility
See Appendix B, “Editing the configuration file ctg.ini,” on page 203 for
information on how to configure the CICS Transaction Gateway by editing the
configuration file. This is the recommended way if you use a screen reader.
The configuration file uses the number sign (#) character to denote a comment;
consider configuring your screen reader accordingly.
Components
Each component in the Configuration Tool has a name and description for screen
readers.
Keys
You can use the following keys to operate the Configuration Tool:
Alt, Space
Press and release the Alt key, then press Space, to open the window menu.
This allows you to move, size, maximize or minimize the window.
Ctrl+key
Certain actions have shortcuts assigned to them. Hold down the Ctrl key and
type the letter to do the action.
Action Ctrl+key
Activate a link. Spacebar
Copy the selected value C except in the following locales:
Locale Key
German
K
Turkish
P
© Copyright IBM Corp. 1996, 2006 215

Action Ctrl+key
Create a new configuration N
Create a new server definition W except in the following locales:
Locale Key
German
N
Italian V
Spanish
V
Turkish
S
Cut the selected value U except in the following locales:
Cycle between the navigation panel, objects on the settings panel,
and the buttons
Next link or other focusable object T
Locale Key
Italian G
Spanish
O
Turkish
E
Use this key combination on panels that contain
a table. Otherwise use Tab.
Open an existing configuration O except in the following locales:
Locale Key
German
F
Italian A
Spanish
B
Turkish
A
Paste P except in the following locales:
Locale Key
French L
German
F
Italian I
Turkish
P
Previous link or other focusable object Shift+T
Save the current configuration S except in the following locales:
216 CICS Transaction Gateway: UNIX and Linux Administration
Locale Key
Spanish
G
Italian L

Action Ctrl+key
Scroll left Page Up
Scroll right Page Down
Arrows (left and right)
1. (Applies if the menus are active.) Move to a different menu.
2. (Applies if the buttons are active.) Cycle through the buttons.
3. (Applies if the navigation panel is active.) If a node contains subnodes, the
left arrow collapses the node, the right arrow expands it. If a node cannot
be expanded further, pressing the right arrow moves down to the next
node. If a subnode is selected, pressing the left arrow moves to the parent
node.
Arrows (up and down)
1. (Applies if the navigation panel is active.) Move up and down through the
navigation panel.
2. (Applies if the buttons are active.) Cycle through the buttons.
3. (Applies if the Authorized Hosts list box is active.) Move through the
entries in the list. If only one entry is in the list, press the Home key to
select it.
Escape
Closes the menu.
F2 Select and change an editable number field in a table.
F6 (Applies if the navigation panel or the settings panel is active.) Toggles
between the navigation panel and the settings panel.
F8 (Applies if the navigation panel or the settings panel is active.) Allows you to
gain control of the split between the navigation panel and settings panel areas.
After pressing F8, use the arrow keys to move the split:
v Press the left arrow key to move the split left (decrease the width of the
navigation panel, increase the width of the settings panel).
v Press the right arrow key to move the split right (increase the width of the
navigation panel, decrease the width of the settings panel).
F10
Opens the file menu.
Home
Selects the first entry in the Authorized Hosts list box.
Page Up
Scroll up.
Page Down
Scroll down.
Scroll bars
You cannot use the keyboard to control scroll bars in the navigation panel. Use
the up and down arrow keys to navigate the tree; settings for the selected item
are shown in the settings panel.
Shift+Tab
If the cursor is on a field in the settings panel other than the first field, moves
backwards through the fields. Otherwise, toggles between the navigation panel
and the settings panel.
Accessibility features for CICS Transaction Gateway 217

cicsterm
Space
1. Activates a button.
2. Selects a check box.
3. Selects a node in the tree.
Tab
Cycles through the tree, fields in the settings panel, and the buttons.
Customizing colors and fonts
Use the Settings option on the menu to change colors and fonts.
Fields that contain errors are displayed by default in the font warning color,
preceded by an asterisk. Use the Settings->Font option on the menu to change the
warning color.
Although cicsterm is accessible, it relies on the application that is being processed
to define an accessible 3270 screen. Keyboard mapping depends on the terminal
type that you are using; see “Keyboard mapping in cicsterm” on page 145 for
details.
The bottom row of cicsterm contains status information. The following list shows
this information, as it appears from left to right:
Status For example, 1B is displayed while cicsterm is connecting to a server.
Displayed at columns 1 – 3.
Terminal name
Also referred to as LU Name. Columns 4 – 7.
Action
For example, X-System, indicating that you cannot enter text in the
terminal window because cicsterm is waiting for a response from the
server. Columns 9 – 16.
Error number
Errors in the form CCLNNNN, relating to the CICS Transaction Gateway.
Columns 17 – 24.
Server name
The server to which cicsterm is connected. Columns 27 – 35.
Upper case
An up arrow is displayed when the Shift key is pressed. Column 42.
Caps Lock
A capital A is displayed when Caps Lock is on. Column 43.
Insert on
The caret symbol (^) is displayed if text will be inserted, rather than
overwriting existing text. If you have difficulty seeing the caret, change the
font face and size, or use a screen magnifier to increase the size of the
status line. Column 52.
Cursor position
The cursor position, in the form ROW/COLUMN, where ROW is a
two-digit number, and COLUMN a three-digit number. The top left of the
screen is 01/001. Column 75–80.
218 CICS Transaction Gateway: UNIX and Linux Administration

Note: You might need to change the default behavior of your screen
reader if it reads only the last digit of the cursor position. Customize
your screen reader to specify that columns 75–80 of the status row
are to be treated as one field. This will cause the full area to be read
when any digit changes.
Accessibility features for CICS Transaction Gateway 219

220 CICS Transaction Gateway: UNIX and Linux Administration

Glossary
This glossary defines special terms used in the CICS Transaction Gateway library.
3270 emulation
The use of software that enables a client to emulate an IBM 3270 display
station or printer, and to use the functions of an IBM host system.
abnormal end of task (abend)
The termination of a task, job, or subsystem because of an error condition
that recovery facilities cannot resolve.
Advanced program-to-program communication (APPC)
An implementation of the SNA/SDLC LU 6.2 protocol that allows
interconnected systems to communicate and share the processing of
programs. The Client daemon uses APPC to communicate with CICS
server systems.
APAR See Authorized program analysis report.
API Application programming interface.
applet A small application program that performs a specific task and is usually
portable between operating systems. Often written in Java, applets can be
downloaded from the Internet and run in a Web browser.e
application identifier
The name by which a logical unit is known in a VTAM network. The CICS
applid is specified in the APPLID system initialization parameter.
application programming interface (API)
A functional interface that allows an application program that is written in
a high-level language to use specific data or functions of the operating
system or another program.
applid See application identifier.
ARM See automatic restart management.
Authorized program analysis report (APAR)
A request for correction of a defect in a current release of an IBM-supplied
program.
ATI See automatic transaction initiation.
attach In SNA, the request unit that flows on a session to initiate a conversation.
Attach Manager
The component of APPC that matches attaches received from remote
computers to accepts issued by local programs.
autoinstall
A method of creating and installing resources dynamically as terminals log
on, and deleting them at logoff.
automatic restart manager
A z/OS recovery function that can improve the availability of specific
batch jobs or started tasks, and therefore result in faster resumption of
productive work. Acronym: ARM.
© Copyright IBM Corp. 1996, 2006 221

automatic transaction initiation (ATI)
The initiation of a CICS transaction by an internally generated request, for
example, the issue of an EXEC CICS START command or the reaching of a
transient data trigger level. CICS resource definition can associate a trigger
level and a transaction with a transient data destination. When the number
of records written to the destination reaches the trigger level, the specified
transaction is automatically initiated.
bean A definition or instance of a JavaBeans component. See also JavaBeans.
bean-managed transaction
A transaction where the J2EE bean itself is responsible for administering
transaction tasks such as committal or rollback. See also container-managed
transaction.
BIND command
In SNA, a request to activate a session between two logical units (LUs).
business logic
The part of a distributed application that is concerned with the application
logic rather than the user interface of the application. Compare with
presentation logic.
CA See certificate authority.
callback
A way for one thread to notify another application thread that an event
has happened.
certificate authority
In computer security, an organization that issues certificates. The certificate
authority authenticates the certificate owner’s identity and the services that
the owner is authorized to use. It issues new certificates and revokes
certificates from users who are no longer authorized to use them.
change-number-of-sessions (CNOS)
An internal transaction program that regulates the number of parallel
sessions between the partner LUs with specific characteristics.
CICS on System/390
A generic reference to the products CICS Transaction Server for z/OS,
CICS for MVS/ESA , CICS Transaction Server for VSE/ESA, and
CICS/VSE.
class In object-oriented programming, a model or template that can be
instantiated to create objects with a common definition and therefore,
common properties, operations, and behavior. An object is an instance of a
class.
classpath
In the execution environment, an environment variable keyword that
specifies the directories in which to look for class and resource files.
Client API
This is the interface used by Client applications to invoke services in CICS
using the facilities of the Client daemon. See External Call Interface,
External Presentation Interface and External Security Interface.
Client application
A user application written in a supported programming language, other
than Java, that uses the Client API.
222 CICS Transaction Gateway: UNIX and Linux Administration

Client daemon
The Client daemon, process cclclnt, exists only on UNIX, Windows and
Linux. It manages network connections to CICS servers. It processes ECI,
EPI, and ESI requests, sending and receiving the appropriate flows from
the CICS server to satisfy the application requests. It uses the CLIENT
section of ctg.ini for its configuration.
client/server
Pertaining to the model of interaction in distributed data processing in
which a program on one computer sends a request to a program on
another computer and awaits a response. The requesting program is called
a client; the answering program is called a server.
CNOS See Change-Number-of-Sessions.
code page
An assignment of hexadecimal identifiers (code points) to graphic
characters. Within a given code page, a code point can have only one
meaning.
color mapping file
A file that is used to customize the 3270 screen color attributes on client
workstations.
commit phase
The second phase in a XA process. If all participants acknowledge that
they are prepared to commit , the transaction manager issues the commit
request. If any participant is not prepared to commit the transaction
manager issues a back-out request to all participants.
communication area (COMMAREA)
A communication area that is used for passing data both between
programs within a transaction and between transactions.
configuration file
A file that specifies the characteristics of a program, system device, server
or network.
connection
In data communication, an association established between functional units
for conveying information.
In Open Systems Interconnection architecture, an association established by
a given layer between two or more entities of the next higher layer for the
purpose of data transfer.
In TCP/IP, the path between two protocol application that provides
reliable data stream delivery service.
In Internet, a connection extends from a TCP application on one system to
a TCP application on another system.
container-managed transaction
A transaction where the EJB container is responsible for administration of
tasks such as committal or rollback. See also bean-managed transaction.
control table
In CICS, a storage area used to describe or define the configuration or
operation of the system.
conversation
A connection between two programs over a session that allows them to
communicate with each other while processing a transaction.
Glossary 223

|
conversation security
In APPC, a process that allows validation of a user ID or group ID and
password before establishing a connection.
daemon
A program that runs unattended to perform continuous or periodic
systemwide functions, such as network control. A daemon may be
launched automatically, such as when the operating system is started, or
manually.
data link control (DLC)
A set of rules used by nodes on a data link (such as an SDLC link or a
token ring) to accomplish an orderly exchange of information.
DBCS See double-byte character set.
dependent logical unit
A logical unit that requires assistance from a system services control point
(SSCP) to instantiate an LU-to-LU session.
deprecated
Pertaining to an entity, such as a programming element or feature, that is
supported but no longer recommended, and that might become obsolete.
digital certificate
An electronic document used to identify an individual, server, company, or
some other entity, and to associate a public key with the entity. A digital
certificate is issued by a certificate authority and is digitally signed by that
authority.
digital signature
Information that is encrypted with an entity’s private key and is appended
to a message to assure the recipient of the authenticity and integrity of the
message. The digital signature proves that the message was signed by the
entity that owns, or has access to, the private key or shared secret
symmetric key.
distributed application
An application for which the component application programs are
distributed between two or more interconnected processors.
distributed processing
The processing of different parts of the same application in different
systems, on one or more processors.
distributed program link (DPL)
A link that enables an application program running on one CICS system to
link to another application program running in another CICS system.
DLL See dynamic link library.
domain
In the Internet, a part of a naming hierarchy in which the domain name
consists of a sequence of names (labels) separated by periods (dots).
domain name
In TCP/IP, a name of a host system in a network.
domain name server
In TCP/IP, a server program that supplies name-to-address translation by
mapping domain names to internet addresses. Synonymous with name
server.
224 CICS Transaction Gateway: UNIX and Linux Administration

|
|
dotted decimal notation
The syntactical representation for a 32-bit integer that consists of four 8-bit
numbers written in base 10 with periods (dots) separating them. It is used
to represent IP addresses.
double-byte character set (DBCS)
A set of characters in which each character is represented by 2 bytes.
Languages such as Japanese, Chinese and Korean, which contain more
symbols than can be represented by 256 code points, require double-byte
character sets. Because each character requires 2 bytes, the typing, display,
and printing of DBCS characters requires hardware and programs that
support DBCS. Contrast with single-byte character set.
DPL See distributed program link.
dynamic link library (DLL)
A collection of runtime routines made available to applications as required.
EBCDIC
See Extended binary-coded decimal interchange code.
ECI See external call interface.
EJB See Enterprise JavaBeans.
emulation program
A program that allows a host system to communicate with a workstation
in the same way as it would with the emulated terminal.
emulator
A program that causes a computer to act as a workstation attached to
another system.
encryption
The process of transforming data into an unintelligible form in such a way
that the original data can be obtained only by using a decryption process.
enterprise bean
A Java component that can be combined with other resources to create
J2EE applications. There are three types of enterprise beans: entity beans,
session beans, and message-driven beans.
Enterprise JavaBeans
A component architecture defined by Sun Microsystems for the
development and deployment of object-oriented, distributed,
enterprise-level applications (J2EE).
environment variable
A variable that specifies the operating environment for a process. For
example, environment variables can describe the home directory, the
command search path, the terminal in use, and the current time zone.
EPI See external presentation interface.
ESI See external security interface.
Ethernet
A local area network that allows multiple stations to access the
transmission medium at will without prior coordination, avoids contention
by using carrier sense and deference, and resolves contention by using
collision detection and transmission. Ethernet uses carrier sense multiple
access with collision detection (CSMA/CD).
EXCI See External CICS Interface.
Glossary 225

|
|
|
external call interface (ECI)
A facility that allows a non-CICS program to run a CICS program. Data is
exchanged in a COMMAREA as for normal CICS interprogram
communication.
Extended binary-coded decimal interchange code (EBCDIC)
A coded character set of 256 8-bit characters developed for the
representation of textual data.
extended logical unit of work (extended LUW)
A logical unit of work that is extended across successive ECI requests to
the same CICS server.
External CICS Interface (EXCI)
An MVS application programming interface provided by CICS Transaction
Server for z/OS that enables a non-CICS program to call a CICS program
and to pass and receive data by means of a COMMAREA. The CICS
application program is invoked as if linked-to by another CICS application
program. The EXCI is used as the communications interface by the CICS
Transaction Gateway for z/OS. Compare with External Call Interface (ECI).
external presentation interface (EPI)
A facility that allows a non-CICS program to appear to CICS as one or
more standard 3270 terminals. 3270 data can be presented to the user by
emulating a 3270 terminal or by using a graphical user interface.
external security interface (ESI)
A facility that enables client applications to verify and change passwords
for user IDs on CICS servers.
firewall
A configuration of software that prevents unauthorized traffic between a
trusted network and an untrusted network.
gateway
A device or program used to connect two systems or networks.
gateway classes
This is the Java class library used by Java Client applications to invoke
services in CICS.
Gateway daemon
This is a long running Java process used only in remote mode. The
Gateway daemon listens for network requests from remote Java Client
applications. It issues these requests to CICS using the facilities of the
Client daemon on UNIX, Windows and Linux platforms, or using the EXCI
on z/OS. The Gateway daemon runs the protocol listener threads, the
connection manager threads and the worker threads. It uses the GATEWAY
section of ctg.ini (and on z/OS the STDENV file or the ctgenvvar script)
for its configuration.
Gateway group
A collection of Gateway daemon instances, that uses the services of a
single ctgmaster. The group provides a TCP/IP load balancing capability
for XA transactions.
gateway token
Gateway tokens are used in the statistical data API. A token represents a
specific Gateway daemon, once a connection is established successfully.
226 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
global transaction
A recoverable unit of work performed by one or more resource managers
in a distributed transaction processing environment and coordinated by an
external transaction manager.
host A computer that is connected to a network (such as the Internet or an SNA
network) and provides an access point to that network. The host can be
any system; it does not have to be a mainframe.
host address
An IP address that is used to identify a host on a network.
host ID
In TCP/IP, that part of the Internet address that defines the host on the
network. The length of the host ID depends on the type of network or
network class (A, B, or C).
host name
In the Internet suite of protocols, the name given to a computer.
Sometimes, host name is used to mean the fully qualified domain name;
other times, it is used to mean the most specific subname of a fully
qualified domain name. For example, if mycomputer.city.company.com is
the fully qualified domain name, either of the following may be considered
the host name: mycomputer.city.company.com, mycomputer.
hover help
Information that can be viewed by holding a mouse over an item such as
an icon in the user interface.
HTTP See Hypertext Transfer Protocol.
HTTPS
See Hypertext Transfer Protocol Secure.
Hypertext Transfer Protocol
In the Internet suite of protocols, the protocol that is used to transfer and
display hypertext and XML documents.
Hypertext Transfer Protocol Secure
A TCP/IP protocol that is used by World Wide Web servers and Web
browsers to transfer and display hypermedia documents securely across
the Internet.
ID data
An ID data structure holds an individual result from a statistical API
function.
iKeyman
A tool for maintaining digital certificates for JSSE.
independent logical unit
A logical unit (LU) that can both send and receive a BIND, and which
supports single, parallel, and multiple sessions. See BIND.
Internet Architecture Board
The technical body that oversees the development of the internet suite of
protocols known as TCP/IP.
Internet Protocol (IP)
In TCP/IP, a protocol that routes data from its source to its destination in
an Internet environment.
Glossary 227

interoperability
The capability to communicate, execute programs, or transfer data among
various functional units in a way that requires the user to have little or no
knowledge of the unique characteristics of those units.
IP Internet Protocol.
IP address
A unique address for a device or logical unit on a network that uses the IP
standard.
J2EE See Java 2 Platform Enterprise Edition
J2EE Connector architecture (JCA)
A standard architecture for connecting the J2EE platform to heterogeneous
enterprise information systems (EIS).
Java An object-oriented programming language for portable interpretive code
that supports interaction among remote objects.
Java 2 Platform Enterprise Edition (J2EE)
An environment for developing and deploying enterprise applications,
defined by Sun Microsystems Inc. The J2EE platform consists of a set of
services, application programming interfaces (APIs), and protocols that
allow multitiered, Web-based applications to be developed.
JavaBeans
As defined for Java by Sun Microsystems, a portable, platformindependent,
reusable component model.
Java Client application
A user application written in Java, including servlets and enterprise beans,
that uses the Gateway classes.
Java Development Kit (JDK)
The name of the software development kit that Sun Microsystems provided
for the Java platform, up to and including v 1.1.x. Sometimes used
erroneously to mean the Java platform or as a generic term for any
software developer kits for Java.
JavaGateway
The URL of the CICS Transaction Gateway with which the Java Client
application will communicate. The JavaGateway takes the form
protocol://address:port. These protocols are supported: tcp://, ssl://,
and local:. The CICS Transaction Gateway runs with the default port
value of 2006. This parameter is not relevant if you are using the protocol
local:. For example, you might specify a JavaGateway of
tcp://ctg.business.com:2006. If you specify the protocol as local: you
will connect directly to the CICS server, bypassing any CICS Transaction
Gateway servers.
Java Native Interface (JNI)
A programming interface that allows Java code running in a Java virtual
machine to work with functions that are written in other programming
languages.
Java Runtime Environment (JRE)
A subset of the Java Software Development Kit (SDK) that supports the
execution, but not the development, of Java applications. The JRE
comprises the Java Virtual Machine (JVM), the core classes, and supporting
files.
228 CICS Transaction Gateway: UNIX and Linux Administration

Java Secure Socket Extension (JSSE)
A Java package that enables secure Internet communications. It implements
a Java version of the Secure Sockets Layer (SSL) and Transport Layer
Security (TSL) protocols and supports data encryption, server
authentication, message integrity, and optionally client authentication.
Java virtual machine (JVM)
A software implementation of a processor that runs compiled Java code
(applets and applications).
JDK See Java development kit (JDK).
JCA See J2EE Connector Architecture (JCA).
JNI See Java Native Interface (JNI).
JRE See Java Runtime Environment
JSSE See Java Secure Socket Extension (JSSE).
JVM See Java Virtual Machine (JVM).
keyboard mapping
A list that establishes a correspondence between keys on the keyboard and
characters displayed on a display screen, or action taken by a program,
when that key is pressed.
key ring
In the JSSE protocol, a file that contains public keys, private keys, trusted
roots, and certificates.
local mode
A term that describes the use of the CICS Transaction Gateway local
protocol. The Gateway daemon is not used in local mode.
local transaction
A recoverable unit of work managed by a resource manager and not
coordinated by an external transaction manager
logical unit (LU)
In SNA, a port through which an end user accesses the SNA network in
order to communicate with another end user and through which the end
user accesses the functions provided by system services control points
(SSCP). An LU can support at least two sessions, one with an SSCP and
one with another LU, and may be capable of supporting many sessions
with other logical units. See network addressable unit, primary logical unit,
secondary logical unit.
logical unit 6.2 (LU 6.2)
A type of logical unit that supports general communications between
programs in a distributed processing environment.
The LU type that supports sessions between two applications using APPC.
logical unit of work (LUW)
A recoverable unit of work performed within CICS.
LU-LU session
In SNA, a session between two logical units (LUs) in an SNA network. It
provides communication between two end users, or between an end user
and an LU services component.
Glossary 229

LU-LU session type 6.2
In SNA, a type of session for communication between peer systems.
Synonymous with APPC protocol.
LUW See logical unit of work.
managed mode
Describes an environment in which connections are obtained from
connection factories that the J2EE server has set up. Such connections are
owned by the J2EE server.
medium access control (MAC) sublayer
One of two sublayers of the ISO Open Systems Interconnection data link
layer proposed for local area networks by the IEEE Project 802 Committee
on Local Area Networks and the European Computer Manufacturers
Association (ECMA). It provides functions that depend on the topology of
the network and uses services of the physical layer to provide services to
the logical link control (LLC) sublayer. The OSI data link layer corresponds
to the SNA data link control layer.
method
In object-oriented programming, an operation that an object can perform.
An object can have many methods.
mode In SNA, a set of parameters that defines the characteristics of a session
between two LUs.
name server
In TCP/IP, synonym for Domain Name Server. In Internet
communications, a host that translates symbolic names assigned to
networks and hosts into Internet addresses.
network address
In SNA, an address, consisting of subarea and element fields, that
identifies a link, link station, or network addressable unit (NAU). Subarea
nodes use network addresses; peripheral nodes use local addresses. The
boundary function in the subarea node to which a peripheral node is
attached transforms local addresses to network addresses and vice versa.
See also network name.
network addressable unit (NAU)
In SNA, a logical unit, a physical unit, or a system services control point.
The NAU is the origin or the destination of information transmitted by the
path control network. See also logical unit, network address, network name.
network name
In SNA, the symbolic identifier by which end users refer to a network
addressable unit (NAU), link station, or link. See also network address.
node type
In SNA, a designation of a node according to the protocols it supports and
the network addressable units (NAUs) it can contain. Four types are
defined: 1, 2, 4, and 5. Type 1 and type 2 nodes are peripheral nodes; type
4 and type 5 nodes are subarea nodes.
nonmanaged mode
An environment in which the application is responsible for generating and
configuring connection factories. The J2EE server does not own or know
about these connection factories and therefore provides no Quality of
Service facilities.
230 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
object In object-oriented programming, a concrete realization of a class that
consists of data and the operations associated with that data.
object-oriented (OO)
Describing a computer system or programming language that supports
objects.
one-phase commit
A protocol with a single commit phase, that is used for the coordination of
changes to recoverable resources when a single resource manager is
involved.
pacing
A technique by which a receiving station controls the rate of transmission
of a sending station to prevent overrun.
parallel session
In SNA, two or more concurrently active sessions between the same two
LUs using different pairs of network addresses. Each session can have
independent session parameters.
PING In Internet communications, a program used in TCP/IP networks to test
the ability to reach destinations by sending the destinations an Internet
Control Message Protocol (ICMP) echo request and waiting for a reply.
partner logical unit (PLU)
In SNA, the remote participant in a session.
partner transaction program
The transaction program engaged in an APPC conversation with a local
transaction program.
PLU See primary logical unit and partner logical unit.
port An endpoint for communication between devices, generally referring to a
logical connection. A 16-bit number identifying a particular Transmission
Control Protocol (TCP) or User Datagram Protocol (UDP) resource within a
given TCP/IP node.
prepare phase
The first phase of a XA process in which all participants are requested to
confirm readiness to commit.
presentation logic
The part of a distributed application that is concerned with the user
interface of the application. Compare with business logic.
primary logical unit (PLU)
In SNA, the logical unit that contains the primary half-session for a
particular logical unit-to-logical unit (LU-to-LU) session. See also secondary
logical unit.
protocol boundary
The signals and rules governing interactions between two components
within a node.
Query strings
Query strings are used in the statistical data API. A query string is an
input parameter, specifying the statistical data to be retrieved.
Resource Access Control Facility (RACF)
An IBM licensed program that provides access control by identifying users
to the system; verifying users of the system; authorizing access to protected
Glossary 231

|
|
|
|
|
|
|
|
|
|
|
|
|
|
resources; logging detected unauthorized attempts to enter the system; and
logging detected accesses to protected resources.
region In workload management on CICS Transaction Gateway for Windows, an
instance of a CICS server.
remote mode
A term that describes the use of one of the supported CICS Transaction
Gateway network protocols to connect to the Gateway daemon. See
Gateway daemon.
remote procedure call (RPC)
A protocol that allows a program on a client computer to run a program
on a server.
request unit (RU)
In SNA, a message unit that contains control information such as a request
code, or function management (FM) headers, end-user data, or both.
request/response unit
A generic term for a request unit or a response unit. See also request unit
and response unit.
response file
A file that contains a set of predefined answers to questions asked by a
program and that is used in place of a user dialog. See CID methodology.
response unit (RU)
A message unit that acknowledges a request unit; it may contain prefix
information received in a request unit.
resource group ID
A resource group ID is a logical grouping of resources, grouped for
statistical purposes. A resource group ID is associated with a number of
resource group statistics, each identified by a statistic ID.
resource ID
A resource ID refers to a specific resource. Information about the resource
is included in resource-specific statistics. Each statistic is identified by a
statistic ID.
resource manager
The participant in a transaction responsible for controlling access to
recoverable resources. In terms of the CICS resource adapters this is
represented by an instance of a ConnectionFactory.
Resource Recovery Services (RRS)
A z/OS facility that provides two-phase sync point support across
participating resource managers.
Result set
A result set is a set of data calculated or recorded by a statistical API
function.
Result set token
A result set token is a reference to the set of results returned by a statistical
API function.
rollback
An operation in a transaction that reverses all the changes made during the
unit of work. After the operation is complete, the unit of work is finished.
Also known as a backout.
232 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
RU Request unit. Response unit.
RPC See remote procedure call.
SBCS See single-byte character set.
secondary logical unit (SLU)
In SNA, the logical unit (LU) that contains the secondary half-session for a
particular LU-LU session. Contrast with primary logical unit. See also
logical unit.
Secure Sockets Layer (SSL)
A security protocol that provides communication privacy. SSL enables
client/server applications to communicate in a way that is designed to
prevent eavesdropping, tampering, and message forgery. SSL applies only
to internet protocols, and is not applicable to SNA.
servlet
A Java program that runs on a Web server and extends the server’s
functionality by generating dynamic content in response to Web client
requests. Servlets are commonly used to connect databases to the Web.
session limit
In SNA, the maximum number of concurrently active logical unit to logical
unit (LU-to-LU) sessions that a particular logical unit (LU) can support.
single-byte character set (SBCS)
A character set in which each character is represented by 1 byte. Contrast
with double-byte character set.
sign-on capable terminal
A sign-on capable terminal allows sign-on transactions, either
CICS-supplied (CESN) or user-written, to be run. Contrast with sign-on
incapable terminal.
SIT See system initialization table.
SNA sense data
An SNA-defined encoding of error information In SNA, the data sent with
a negative response, indicating the reason for the response.
SNASVCMG mode name
The SNA service manager mode name. This is the architecturally-defined
mode name identifying sessions on which CNOS is exchanged. Most
APPC-providing products predefine SNASVCMG sessions.
socket A network communication concept, typically representing a point of
connection between a client and a server. A TCP/IP socket will normally
combine a host name or IP address, and a port number.
SSL See Secure Sockets Layer (SSL).
SSLight
An implementation of SSL, written in Java, and no longer supported by
CICS Transaction Gateway.
statistic data
A statistic data structure holds individual statistical result returned after
calling a statistical API function.
statistic group
A statistic group is a generic term for a collection of statistic IDs.
Glossary 233

|
|
|
|
statistic ID
A statistic ID is a label refering to a specific statistic. A statistic ID is used
to retrieve specific statistical data, and always has a direct relationship
with a statistic group.
system initialization table
A table containing parameters used to start a CICS control region.
System Management Interface Tool (SMIT)
An interface tool of the AIX operating system for installing, maintaining,
configuring, and diagnosing tasks.
standard error
In many workstation-based operating systems, the output stream to which
error messages or diagnostic messages are sent.
subnet
An interconnected, but independent segment of a network that is identified
by its Internet Protocol (IP) address.
subnet address
In Internet communications, an extension to the basic IP addressing scheme
where a portion of the host address is interpreted as the local network
address.
sync point
A logical point in the execution of program where the changes made by
the program are consistent and complete, and can be committed. The
output, which has been held up to that point, is sent to its destination, the
input is removed from the message queues, and updates are made
available to other applications. When a program terminates abnormally,
CICS recovery and restart facilities do not backout updates prior to the last
completed sync point.
Systems Network Architecture (SNA)
An architecture that describes the logical structure, formats, protocols, and
operational sequences for transmitting information units through the
networks and also the operational sequences for controlling the
configuration and operation of networks.
System SSL
An implementation of SSL, no longer supported by CICS Transaction
Gateway on z/OS.
TCP62 SNA logical unit type 62 (LU62) protocol encapsulated in TCP/IP. This
allows APPC applications to communicate over a TCP/IP Network without
changes to the applications.
TCP/IP
See Transmission Control Protocol/Internet Protocol.
TCP/IP load balancing
The ability to distribute TCP/IP connections across target servers.
terminal emulation
The capability of a microcomputer or personal computer to operate as if it
were a particular type of terminal linked to a processing unit and to access
data. See also emulator, emulation program.
thread A stream of computer instructions that is in control of a process. In some
operating systems, a thread is the smallest unit of operation in a process.
Several threads can run concurrently, performing different jobs.
234 CICS Transaction Gateway: UNIX and Linux Administration

|
|
|
|
|
|
|
timeout
A time interval that is allotted for an event to occur or complete before
operation is interrupted.
TLS See Transport Layer Security (TLS).
token-ring network
A local area network that connects devices in a ring topology and allows
unidirectional data transmission between devices by a token-passing
procedure. A device must receive a token before it can transmit data.
trace A record of the processing of a computer program. It exhibits the
sequences in which the instructions were processed.
transaction manager
A software unit that coordinates the activities of resource managers by
managing global transactions and coordinating the decision to commit
them or roll them back.
transaction program
A program that uses the Advanced Program-to-Program Communications
(APPC) application programming interface (API) to communicate with a
partner application program on a remote system.
Transmission Control Protocol/Internet Protocol (TCP/IP)
An industry-standard, nonproprietary set of communications protocols that
provide reliable end-to-end connections between applications over
interconnected networks of different types.
Transport Layer Security (TLS)
A security protocol that provides communication privacy. TLS enables
client/server applications to communicate in a way that is designed to
prevent eavesdropping, tampering, and message forgery. TLS applies only
to internet protocols, and is not applicable to SNA. TLS is also known as
SSL 3.1.
two-phase commit
A protocol with both a prepare and a commit phase, that is used for the
coordination of changes to recoverable resources when more than one
resource manager is used by a single transaction.
type 2.0 node
A node that attaches to a subarea network as a peripheral node and
provides a range of end-user services but no intermediate routing services.
type 2.1 node
An SNA node that can be configured as an endpoint or intermediate
routing node in a network, or as a peripheral node attached to a subarea
network.
Uniform Resource Locator (URL)
A sequence of characters that represent information resources on a
computer or in a network such as the Internet. This sequence of characters
includes (a) the abbreviated name of the protocol used to access the
information resource and (b) the information used by the protocol to locate
the information resource.
unit of recovery (UR)
A defined package of work to be performed by the RRS.
unit of work (UOW)
A recoverable sequence of operations performed by an application between
Glossary 235

|
|
|
two points of consistency. A unit of work begins when a transaction starts
or at a user-requested syncpoint. It ends either at a user-requested
syncpoint or at the end of a transaction.
user session
Any APPC session other than a SNASVCMG session.
verb A reserved word that expresses an action to be taken by an application
programming interface (API), a compiler, or an object program.
In SNA, the general name for a transaction program’s request for
communication services.
version string
A character string containing version information about the statistical data
API.
Web browser
A software program that sends requests to a Web server and displays the
information that the server returns.
Web server
A software program that responds to information requests generated by
Web browsers.
wide area network (WAN)
A network that provides communication services to a geographic area
larger than that served by a local area network or a metropolitan area
network, and that may use or provide public communication facilities.
wrapping trace
A configuration in which the Maximum Client wrap size setting is greater
than 0. The total size of Client daemon binary trace files is limited to the
value specified in the Maximum Client wrap size setting. With standard
I/O tracing, two files, called cicscli.bin and cicscli.wrp, are used; each
can be up to half the size of the Maximum Client wrap size.
XA transaction
A global transaction that adheres to the X/Open standard for distributed
transaction processing (DTP.)
236 CICS Transaction Gateway: UNIX and Linux Administration

Index
Special characters
(External Call Interface) 1, 4
(External Presentation Interface) 1, 4
(External Security Interface) 1, 4
(TCP62) 76
viii
A
accessibility 215
Acrobat 24
adding features 32
administration 126
Adobe 24
advanced program-to-program communication (APPC) 41
Advanced Program-to-Program Communication (APPC) 25
AnyNet domain name suffix configuration setting 77
APAR (authorized program analysis report)
authorization 180
closing 180
documentation needed 178
process 180
submitting 180
API (Application Programming Interface) 3
APPC (advanced program-to-program communication) 41
APPC (Advanced Program-to-Program Communication) 25
application development tools 23
Application ID configuration setting 65
Application Programming Interface (API) 3
application servers 22
application tracing 156
asymmetric keys 7
authentication 9
B
background task 126
binary trace formatter 164
Bind Address 60, 205
Bind Address configuration setting 60
books 211
browsers 21
C
CA (certification authority) 8
ccllog.hlp 162
cclmsg.hlp 162
certification authority (CA) 8
CICS resource adapters 82
CICS server PTF requirements 24
CICS servers 22
CICS servers, communicating with 37
CICS Transaction Gateway 125, 126
CICS Transaction Gateway Version 4 183
CICS_EPI_ERR_FAILED 121
cicscli command 133
CICSCLI environment variable 50
cicscli.bin 162, 163, 164
cicscli.log 68, 162
cicscli.trc 162
cicscli.wrp 163
CICSCOL environment variable 91
cicseci resource adapters 82
cicseci.rar 82
cicsepi.rar 82
cicsftrc utility 164
CICSKEY environment variable 90
cicsprnt command 147
cicsterm command 143
CLASSPATH 49
CLASSPATH environment variable 106, 159
client control 5
Client daemon 133, 134
Client daemon, restarting 134
Client daemon, shutting down 134
Client daemon, starting 133, 134
Client daemon, stopping 134
client security 136
Client trace file configuration setting 80
Client trace file wrap size (KB) configuration setting 81
client tracing 135
security considerations 136
client/server connections 25
ClientSecurity 84, 85
code page identifier override configuration setting 68
code page problems 157
code pages 27
color mapping file 91, 143
Common Client Interface (CCI) 11
Communicating with CICS servers 37
communication
cicscli 133
cicsprnt 147
cicsterm 143
problems 174
communication protocols 23
APPC 25
TCP/IP 25
Communications server 176
compilers 23
configuration
CLASSPATH 49
programming environment 49
configuration file 50, 182
referencing 50
configuration settings
Log file 68
Configuration settings
AnyNet domain name suffix 77
Application ID 65
Bind Address 60
Client trace file 80
Client trace file wrap size (KB) 81
code page identifier override 68
Connection timeout 73
Connection timeout (ms) 61
Description 71
Display TCP/IP hostnames 57
Drop working connections 62
© Copyright IBM Corp. 1996, 2006 237

Configuration settings (continued)
Enable protocol handler 60
Enable reading input from console 55
Error and warning log destination 58
Error log file name 58
Error log maximum size (KB) 58
Fully qualified CP name or template 76
Gateway trace file 80
Gateway trace file wrap size (KB) 80
Hostname or IP address 72
Idle timeout (ms) 61
Information log destination 59
Information log file 69
Information log file name 59
Information log maximum size (KB) 59
Initial number of Connection Manager threads 53
Initial number of Worker threads 54
Initial transaction 71
IP address mask for CP name (optional) 77
IP address mask for LU name template (optional) 75
Java clients obtaining generic ECI replies 55
Key ring file 63
Key ring password 64
Local LU name 74
Local LU name or template 74
Log Java Client connections and disconnections 58
Log terminal installations and deinstallations 68
Maximum buffer size 66
Maximum logical SNA sessions 78
Maximum number of archived error log files 58
Maximum number of archived information log files 59
Maximum number of Connection Manager threads 54
Maximum number of Worker threads 54
Maximum requests 67
Maximum servers 66
Maximum SNA RU size 78
Mode name 74, 76
Model terminal definition 71
Partner LU name 74
Ping time frequency (ms) 61
Port 61, 73
Port for local administration 57
Print command 67
Print file 67
Remote node inactivity poll interval(s) 78
Require Java Clients to use security classes 62
Send TCP/IP KeepAlive packets 73
Server idle timeout (mins) 72
Server name 71
Server retry interval 68
SNA pacing size 78
SO_LINGER setting 62
Statistics API port 57
Terminal exit 66
Timeout for in-progress requests to complete (ms) 56
Trace 79
Trace settings 162
Use client authentication 63
Use LU alias names 73
Use only these ciphers 64
Use the same file for information messages 69
Use the same settings for error and information logs 59
Use upper case security 72
Validate message qualifiers 55
Validate Units of Work 55
Worker thread available timeout (ms) 56
Configuration Tool 50
238 CICS Transaction Gateway: UNIX and Linux Administration
connecting to CICS servers 134, 137
Connection timeout (ms) configuration setting 61
Connection timeout configuration setting 73
ConnectionURL 83, 85
Corrective Service Diskette (CSD) 180
corrective service software 32
CPMI 174
CRSR transaction 42
CSD (Corrective Service Diskette) 180
CTG_JNI_TRACE environment variable 81, 157
CTG_JNI_TRACE_ON environment variable 81, 157
ctg.ini 182
ctgclient.jar 159
ctgd command 126
ctgserver.jar 159
customizing
keyboard 89
screen colors 91
D
data conversion
Arabic conversions 194
Baltic Rim conversions 195
Cyrillic conversions 195
Estonian conversions 196
Greek conversions 196
Hebrew conversions 196
Japanese conversions 197
Korean conversions 198
Latin-1 conversions 199
Latin-2 conversions 200
Latin-5 conversions 200
Latin-9 conversions 199
simplified Chinese conversions 201
traditional Chinese conversions 201
Vietnamese conversions 202
Data conversion 45
dbx 172
default installation location viii
defining 3270 printer terminal emulator characteristics 148
defining 3270 terminal emulator characteristics 143
Description configuration setting 71
development tools 23
DeviceType 86
diagnosing common problems
Client daemon 168
code page problems 157
Gateway daemon 157
if a process locks 158
Java exceptions 159
Java security exceptions 159
java.lang.OutOfMemory exception 159
SSL exceptions 158
diagnostic tools
APING 175
digital certificates 7, 9
externally signed 100
maintaining 96
self-signed 97
digital signatures 7
disability 215
disabling the display of messages 137
DISPLAY environment variable 34
Display TCP/IP hostnames configuration setting 57
displaying command syntax 137
distinguished name (DN) 8

DN (distinguished name) 8
documentation 211
documenting problems 178
Drop working connections configuration setting 62
Dump options 130
dump file location 130
dump parameters 130
dump responses 131
Dumps
IBM JVM 161
System JVM 161
E
ECI resource adapters 82
ECI_ERR_SYSTEM_ERROR 121
Enable protocol handler configuration setting 60
Enable reading input from console configuration setting 55
Encoding 86
encryption 7, 9
Enterprise Information Systems (EIS) 10
environment variables
CICSCLI 50
CICSCOL 91
CICSKEY 90
CLASSPATH 49, 106
JAVA_HOME 96
LD_LIBRARY_PATH 93
PATH 93
SHLIB_PATH 93
EPI resource adapter 85
Error and warning log destination configuration setting 58
error log 176
cicscli.log 162
client error log 162
server error log 174
Error log file name configuration setting 58
Error log maximum size (KB) configuration setting 58
euro support 68
EXCI (external CICS interface) 4
EXEC CICS RETURN TRANSID IMMEDIATE command 144,
149
External Call Interface (ECI) 1, 4
external CICS interface (EXCI) 4
External Presentation Interface (EPI) 1, 4
External Security Interface (ESI) 1, 4
externally-signed certificates 8
F
free memory 66
Fully qualified CP name or template configuration setting 76
G
Gateway daemon 126
operating 123
Gateway daemon tracing 156
Gateway daemon with user-specified options 123
Gateway trace file configuration setting 80
Gateway trace file wrap size (KB) 80
Gateway trace file wrap size (KB) configuration setting 80
generic ECI replies
Configuration 55
GhostView 24
glossary of terms and abbreviations 221
H
hangs 158, 171
hardware requirements 19
Hostname or IP address configuration setting 72
I
IBM Communications Server 176
IBM JVM
dump 126
dump responses 131
Idle timeout (ms) configuration setting 61
iKeyMan 96
inactivity poll interval 41
Information log destination configuration setting 59
Information log file configuration setting 69
Information log file name configuration setting 59
Information log maximum size (KB) configuration setting 59
Initial number of Connection Manager threads configuration
setting 53
Initial number of Worker threads configuration setting 54
initial transaction 143, 148
Initial transaction configuration setting 71
initialization files
cicscol.inicicscol.ini 91
cicskey.inicicskey.ini 90
install_path viii
installation 29
adding features 32
complete installation 29
custom installation 29
default location viii
known issues 29
path viii
removing features 32
silent installation 31
types of installation 29
installation path viii
InstallTimeout 86
internal client communication 46
IP address mask for CP name (optional) configuration
setting 77
IP address mask for LU name template (optional)
configuration setting 75
J
J2EE
resource adapter files 82
resource adapters 4
J2EE connector architecture 10
Java
classes 3
installing 31
Java clients obtaining generic ECI replies configuration
setting 55
Java development kit 21
Java exceptions 159
Java Secure Socket Extension (JSSE) 22
Java security exceptions 159
JAVA_HOME environment variable 96
java.lang.OutOfMemory exception 159
JCA 10
JNI trace file 81, 128, 157
JNI tracing 81, 126, 157
Index 239

JRE
installing 31
JSSE 9, 22, 95, 96
migration from SSLight 95
JVM
installing 31
K
KeepAlive packets 41
Key ring file configuration setting 63
Key ring password configuration setting 64
key rings 9
keyboard 215
keyboard mapping file 89, 143
KeyRingClass 84, 86
KeyRingPassword 84, 86
KeyStores 9, 96
keytool 96, 100
L
LD_LIBRARY_PATH 93
libctgjni.so 93
listing connected servers 137
Local LU name configuration setting 74
Local LU name or template configuration setting 74
local mode 11
benefits 12
local support 93
locks 158
Log file configuration setting 68
Log Java Client connections and disconnections configuration
setting 58
log stream 88
Log terminal installations and deinstallations configuration
setting 68
logging 88
logical unit (LU) 41
Logical units of work
extending 118
LogonLogoffClass 86
LU6.2 25
M
MAXACTIVE 174
Maximum buffer size configuration setting 66
Maximum logical SNA sessions configuration setting 78
Maximum number of archived error log files configuration
setting 58
Maximum number of archived information log files
configuration setting 59
Maximum number of Connection Manager threads
configuration setting 54
Maximum number of Worker threads configuration
setting 54
Maximum requests configuration setting 67
Maximum servers configuration setting 66
Maximum SNA RU size configuration setting 78
MAXTASKS 174
memory leak 159
memory mapped tracing 135, 136, 163, 164
memory requirements 66
message queues 46
messages 155, 162
240 CICS Transaction Gateway: UNIX and Linux Administration
messages, disabling the display of 137
messages, redirecting 137
migration viii
support for resource adapters 183
migration issues 183
mode definitions, APPC 41
Mode name configuration setting 74, 76
Model terminal definition configuration setting 71
monitoring 129, 185, 186, 187, 188, 189, 190, 191, 192
N
national language support 33
network security
authentication 9
certification authority (CA) 8
concepts 6
digital certificates 7, 9
externally signed 100
maintaining 96
self-signed 97
digital signatures 7
distinguished name (DN) 8
encryption 7, 9
externally-signed certificates 8
iKeyMan 96
JSSE 9, 95, 96
migration from SSLight 95
key rings 9
keys 7
KeyStores 9, 96
keytool 96, 100
migrating old self-signed certificates 100
security exits 10
self-signed certificates 9
signer certificate 8
SSL 9, 106
SSL handshaking 9
trusted root key 8
X.509 protocol 8, 9
O
online help, for end user messages, 162
online help, for trace and log messages 162
operating
Gateway daemon 123
operating systems 19
operation
CICS Transaction Gateway 125
options
cicscli command 137
cicsprnt command 149
cicsterm command 145
P
Partner LU name configuration setting 74
Password 84, 85
password expiry management (PEM) 4, 109
PATH 93
PEM (password expiry management) 4, 109
performance
assessing 113
configuration 115
considerations 116

performance (continued)
monitoring 118
other system factorssystem considerations 117
tracing 118
Ping time frequency (ms) configuration setting 61
planning 19
PMR (Problem Management Record) 177
Port configuration setting 61, 73
Port for local administration configuration setting 57
PortNumber 83, 85
preset options
ctgstart command 123
Print command configuration setting 67
Print file configuration setting 67
print file, processing 143, 148
print terminal emulator, starting 148
printer support 5
printer terminal emulator characteristics, defining 148
problem determination 153, 173
application tracing 156
diagnosing common problems 168
Gateway daemon 157
Gateway daemon tracing 156
JNI tracing 157
messages 155, 162
preliminary checks 153
tracing
Client daemon 162
Gateway daemon 155
Problem Management Record (PMR) 177
problem reporting
documenting problems 178
information needed 179
support organization 177
problems, communication 174
process locks 158
program support 177
protocols
SSL 1, 9
TCP/IP 1
PTF (Program Temporary Fix) 180
public key encryption 7
publications 211
R
re-authentication support 84, 87
README file 19
ReadTimeout 86
redirecting messages 137
remote mode 11
Remote node inactivity poll interval 41
Remote node inactivity poll interval(s) configuration
setting 78
removing features 32
Require Java Clients to use security classes configuration
setting 62
requirements, hardware 19
resource adapter files 82
resource adapters 82
resource adapters, J2EE 4
restrictions, using CICS servers 26
RETAIN database 177
RETAIN problem management system
APARs 180
Problem Management Record 177
running in the background 126
S
SDKs for Java 21
Secure Sockets Layer (SSL) 1, 9
security 72
External Security Interface (ESI) 4
password expiry management (PEM) 4
security exits 10
self-signed certificates 9
Send TCP/IP KeepAlive packets configuration setting 73
Server idle timeout (mins) configuration setting 72
Server name configuration setting 71
Server retry interval configuration setting 68
ServerName 83, 85
servers
application 22
CICS 22
servers, listing 137
ServerSecurity 84, 85
service 126
SHLIB_PATH 93
shortcut keys 215
sign-on capable terminals 24
signer certificate 8
SignonType 86
silent installation 31
SMIT 172
smitty 172
SNA 23
checking configuration 175
configuring 41
SNA (Systems Network Architecture) 25
sna error log 170
SNA pacing size configuration setting 78
sna.err 176
SO_LINGER setting configuration setting 62
SocketConnectTimeout 83, 85
SSL (Secure Sockets Layer) 1, 9
SSL exceptions 158
SSL handshaking 9
starting a 3270 print terminal emulator 148
starting a 3270 terminal emulator 143
starting and stopping 126
startup options 123
statistics 129, 185, 186, 187, 188, 189, 190, 191, 192
Statistics API port configuration setting 57
stopping 125
stopping a terminal emulator 144
support organization
program support 177
sending documentation to 179
symmetric keys 7
Systems Network Architecture (SNA) 25
T
TCP/IP (Transmission Control Protocol/Internet Protocol) 1,
23, 25, 37
TCP/IP communication problems 169
TCP62 23
port number 77
TCP62 protocol 39
terminal emulation 5
terminal emulator characteristics, defining 143
terminal emulator, starting 143
terminal emulator, stopping 144
Terminal exit configuration setting 66
Index 241

the system locks up 171
timeout 86
Timeout for in-progress requests to complete (ms)
configuration setting 56
TLS 9
tools
application development 23
other 24
TPNName 83
Trace configuration setting 79
Trace settings
Configuration Tool 162
trace, wrapping 163
TraceLevel 84, 87
tracing 87
Client daemon 162
dynamic 126
Gateway daemon 126, 155
JNI 126
levels 87
performance considerations 156
query current trace settings 126
tracing, JNI 157
tracing, memory mapped 135, 136, 163, 164
TranName 83
transaction programs (TP), APPC 41
transaction support 84, 87
transmission control protocol/internet protocol (TCP/IP) 25
Transmission Control Protocol/Internet Protocol (TCP/IP) 1,
25, 37
Transport Layer Security
TLS 105
traps 171
troubleshooting
hangs 171
starting clients and terminals 168
traps 171
trusted root key 8
U
uninstalling 32
updating
installed software 32
upgrading 183
Use client authentication configuration setting 63
Use LU alias names configuration setting 73
Use only these ciphers configuration setting 64
Use the same file for information messages configuration
setting 69
Use the same settings for error and information logs
configuration setting 59
Use upper case security configuration setting 72
Userid 84, 85
V
Validate message qualifiers configuration setting 55
Validate Units of Work configuration setting 55
VTAM
buffer trace 175
242 CICS Transaction Gateway: UNIX and Linux Administration
W
web browsers 21
Worker thread available timeout (ms) configuration
setting 56
wrapping trace 163
X
X-Window System 34
X.509 protocol 8, 9

Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in
other countries. Consult your local IBM representative for information on the
products and services currently available in your area. Any reference to an IBM
product, program, or service is not intended to state or imply that only that IBM
product, program, or service may be used. Any functionally equivalent product,
program, or service that does not infringe any IBM intellectual property right may
be used instead. However, it is the user’s responsibility to evaluate and verify the
operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you
any license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply in the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS
FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore this statement may not apply
to you.
This information could include technical inaccuracies or typographical errors.
Changes are periodically made to the information herein; these changes will be
incorporated in new editions of the information. IBM may make improvements
and/or changes in the product(s) and/or the program(s) described in this
information at any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web
sites. The materials at those Web sites are not part of the materials for this IBM
product and use of those Web sites is at your own risk.
Licensees of this program who wish to have information about it for the purpose
of enabling: (i) the exchange of information between independently created
© Copyright IBM Corp. 1996, 2006 243

Trademarks
programs and other programs (including this one) and (ii) the mutual use of the
information which has been exchanged, should contact IBM United Kingdom
Laboratories, MP151, Hursley Park, Winchester, Hampshire, England, SO21 2JN.
Such information may be available, subject to appropriate terms and conditions,
including in some cases, payment of a fee.
The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Programming License Agreement, or any equivalent agreement
between us.
Information concerning non-IBM products was obtained from the suppliers of
those products, their published announcements or other publicly available sources.
IBM has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-IBM products.
Questions on the capabilities of non-IBM products should be addressed to the
suppliers of those products.
The following terms are trademarks of International Business Machines
Corporation in the United States, or other countries, or both:
AIX
AnyNet
AS/400
CICS
CICS/400
CICS/ESA
CICS/VSE
DB2
Domino
Hummingbird
IBM
IBM
IBMLink
IMS
iSeries
MQSeries
MVS
MVS/ESA
Notes
OS/2
OS/390
POWER
pSeries
RACF
Redbooks
RETAIN
RMF
RS/6000
SAA
SP2
System/390
Tivoli
TXSeries
244 CICS Transaction Gateway: UNIX and Linux Administration

VisualAge
VSE/ESA
VTAM
WebSphere
z/OS
zSeries
Microsoft ® , Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Intel, Intel Inside ®
(logos), MMX
and Pentium ®
are trademarks of Intel
Corporation in the United States, other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or
both.
Other company, product or service names may be trademarks or service marks of
others.
Notices 245

246 CICS Transaction Gateway: UNIX and Linux Administration

Sending your comments to IBM
If you especially like or dislike anything about this book, use one of the methods
listed below to send your comments to IBM.
Feel free to comment on what you regard as specific errors or omissions, and on
the accuracy, organization, subject matter, or completeness of this book.
Limit your comments to the information in this book and the way in which the
information is presented.
To ask questions, make comments about the functions of IBM products or systems,
or to request additional publications, contact your IBM representative or your IBM
authorized remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or
distribute your comments in any way it believes appropriate, without incurring
any obligation to you.
You can send your comments to IBM in any of the following ways:
v By mail, to this address:
User Technologies Department (MP095)
IBM United Kingdom Laboratories
Hursley Park
WINCHESTER,
Hampshire
SO21 2JN
United Kingdom
v By fax:
– +44 1962 842327 (if you are outside the UK)
– 01962 842327 (if you are in the UK)
v Electronically, use the appropriate network ID:
– IBM Mail Exchange: GBIBM2Q9 at IBMMAIL
– IBMLink : HURSLEY(IDRCF)
– Internet: idrcf@hursley.ibm.com
Whichever you use, ensure that you include:
v The publication title and order number
v The topic to which your comment applies
v Your name and address/telephone number/fax number/network ID.
© Copyright IBM Corp. 1996, 2006 247

248 CICS Transaction Gateway: UNIX and Linux Administration

���
Program Number: 5724-I81
SC34-6752-00

Spine information:
��� CICS Transaction Gateway UNIX and Linux Administration Version 7.0