CICS Transaction Gateway Version 5.0

Search
Translated Books
Feedback
CICS Web site
Configuration Scenarios
CICS Transaction Gateway
Windows Administration
UNIX Administration
z/OS Administration
Programming Guide
Programming Reference
CICS
Java Programming Reference (HTML)
Messages

Translated books
The translated books are stand-alone PDF files, which are not included as part of
this library file. They are available for download from the CICS Transaction
Gateway section of the CICS website.

Programming Reference (HTML)
Unfortunately, you cannot link directly to the Programming Reference
from this document; you will need to point your Web browser to:
Operating System
Solaris
AIX
HP-UX
z/OS
Windows
Linux
HTML file
/opt/ctg/docs/en_US/html/javadoc/index.html
/usr/lpp/ctg/docs/en_US/html/javadoc/index.html
/opt/ctg/docs/en_US/html/javadoc/index.html
ctg/docs/en_us/html/javadoc/index.html
/docs/en_US/html/javadoc/index.html
/opt/ctg/docs/en_US/html/javadoc/index.html
You may find it useful to bookmark the HTML file.

CICS Transaction Gateway
Windows Administration
Version 5.0
���
SC34-6190-00

CICS Transaction Gateway
Windows Administration
Version 5.0
���
SC34-6190-00

Note!
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page 295.
First Edition (July 2002)
This edition applies to Version 5.0 of the CICS ® Transaction Gateway, program number 5724-D12. It will also apply to
all subsequent versions, releases, and modifications until otherwise indicated in new editions.
Vertical lines at the left side of the page indicate material that is new to this edition.
© Copyright International Business Machines Corporation 1996, 2002. 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 . . . . . . . . . . ix
Conventions and terminology used in this
book . . . . . . . . . . . . . . . x
Installation path . . . . . . . . . xii
Programming language specific . . . . xii
Operating system specific . . . . . . xii
Syntax notation . . . . . . . . . . xii
Summary of changes . . . . . . . . xv
Chapter 1. Overview . . . . . . . . . 1
What CICS Transaction Gateway provides . . 3
A Gateway daemon. . . . . . . . . 3
The Gateway classes . . . . . . . . 3
J2EE resource adapters . . . . . . . . 3
A Client daemon . . . . . . . . . . 3
The external access interfaces (ECI, EPI, ESI) 3
A Terminal Servlet . . . . . . . . . 4
Additional functions . . . . . . . . . 4
3270 terminal emulation (CICSTERM) . . . 4
3270 printer support (CICSPRNT) . . . . 5
CICS Transaction Gateway: local control . . 5
CICS Transaction Gateway: remote control 6
Network security. . . . . . . . . . . 6
Encryption . . . . . . . . . . . . 7
Digital signatures and digital certificates . . 8
Obtaining a digital certificate. . . . . . 9
KeyRings and KeyStores . . . . . . . 9
Authentication using SSL . . . . . . 10
HTTPS . . . . . . . . . . . . . 12
Security exits. . . . . . . . . . . 12
Java technology . . . . . . . . . . . 12
The Java language . . . . . . . . . 12
Java applets . . . . . . . . . . . 13
Java servlets . . . . . . . . . . . 13
Java applications . . . . . . . . . 13
JavaBeans . . . . . . . . . . . 14
Firewalls . . . . . . . . . . . . 14
Web servers . . . . . . . . . . . 15
The J2EE resource adapters . . . . . . . 15
How CICS Transaction Gateway accesses
CICS . . . . . . . . . . . . . . 16
The CICS Transaction Gateway: threading
model . . . . . . . . . . . . . . 17
|
|
|
CICS Transaction Gateway and object request
brokers. . . . . . . . . . . . . . 19
Workload management . . . . . . . . 19
Chapter 2. Planning your installation . . . 21
Hardware requirements . . . . . . . . 22
Supported software . . . . . . . . . 22
Operating systems . . . . . . . . . 22
Web browsers . . . . . . . . . . 22
Telnet clients . . . . . . . . . . . 23
JDK levels. . . . . . . . . . . . 23
JSSE. . . . . . . . . . . . . . 23
CICS Servers. . . . . . . . . . . 23
Web servers . . . . . . . . . . . 24
Application servers . . . . . . . . 24
SNA communications . . . . . . . . 24
TCP/IP communications . . . . . . . 24
TCP62 communications . . . . . . . 24
Compilers and application development
tools . . . . . . . . . . . . . 25
Screen readers . . . . . . . . . . 25
Other tools . . . . . . . . . . . 25
CICS server PTF requirements . . . . . . 25
Terminal Signon capability . . . . . . 25
Timeout support . . . . . . . . . 25
Communication between the Gateway and
CICS servers . . . . . . . . . . . . 26
Restrictions on CICS for OS/400 . . . . 27
Why use a particular protocol?. . . . . 28
Server Code page support . . . . . . . 28
Chapter 3. Installation . . . . . . . . 29
Choosing what to install . . . . . . . . 29
Microsoft Windows Installer Service . . . . 30
Upgrading . . . . . . . . . . . . 30
Installing the CICS Transaction Gateway . . 31
Actions after installation . . . . . . . . 36
Verify the system path . . . . . . . 36
Creating Start Menu shortcuts . . . . . 36
Maintaining or uninstalling the CICS
Transaction Gateway . . . . . . . . . 37
Updating the CICS Transaction Gateway . . 39
Silent installation . . . . . . . . . . 39
© Copyright IBM Corp. 1996, 2002 iii

|
|
|
|
|
|
Chapter 4. Setting up communication with
CICS servers . . . . . . . . . . . 41
TCP/IP configuration . . . . . . . . . 41
Next steps . . . . . . . . . . . 41
TCP62 configuration . . . . . . . . . 42
On z/OS . . . . . . . . . . . . 43
On CICS Transaction Server for z/OS . . 44
On the workstation . . . . . . . . 44
Firewall implications . . . . . . . . 44
KeepAlive packets . . . . . . . . . 45
Next steps . . . . . . . . . . . 45
SNA configuration . . . . . . . . . . 45
Configuring SNA . . . . . . . . . 46
Named Pipes configuration . . . . . . . 50
Data conversion. . . . . . . . . . . 50
Chapter 5. Configuration . . . . . . . 51
Before you start. . . . . . . . . . . 52
Gather information. . . . . . . . . 52
Log on with administrator privileges. . . 52
Set the JVM . . . . . . . . . . . 52
Set the time . . . . . . . . . . . 53
Configure your programming environment 53
Using the configuration tool . . . . . . 54
Running the configuration tool on a
different operating system . . . . . . 54
The configuration tool interface . . . . 55
Configuring CICS Transaction Gateway
settings . . . . . . . . . . . . 58
Configuring Client settings . . . . . . 71
Configuring Server settings . . . . . . 76
Configuring the Workload Manager . . . 84
Trace settings . . . . . . . . . . 86
Editing the configuration file . . . . . . 89
J2EE setup and configuration . . . . . . 90
Deploying CICS resource adapters . . . 90
Tracing. . . . . . . . . . . . . 95
Sample configuration and mapping files . . 96
Keyboard mapping for CICSTERM . . . . 97
Keyboard mapping file syntax . . . . . 97
The keyboard mapping file . . . . . . 98
Customizing the screen colors for CICSTERM 99
Color mapping syntax . . . . . . . 100
The color mapping file . . . . . . . 101
Preparing to use local CICS Transaction
Gateway support . . . . . . . . . . 101
Chapter 6. Network Security . . . . . 103
Determining your use of SSLight or JSSE for
the SSL and HTTPS protocols . . . . . . 104
iv CICS Transaction Gateway: Windows Administration
|
|
|
|
|
|
|
SSLight . . . . . . . . . . . . . 104
Conflict with JSSE . . . . . . . . 104
Maintaining your digital certificates for
SSLight . . . . . . . . . . . . 104
Using externally signed certificates under
SSLight . . . . . . . . . . . . 105
Using self-signed certificates under
SSLight . . . . . . . . . . . . 110
Java Secure Socket Extension (JSSE) . . . . 114
Migration from SSLight . . . . . . . 114
Installation . . . . . . . . . . . 114
Maintaining your digital certificates for
JSSE . . . . . . . . . . . . . 115
Using externally signed certificates under
JSSE . . . . . . . . . . . . . 115
Using self-signed certificates under JSSE 120
Configuring CICS Transaction Gateway for
SSL and HTTPS . . . . . . . . . . 124
SSL and HTTPS configuration settings 124
Specifying a client KeyRing or KeyStore 125
Using the SSL and HTTPS protocols . . 125
Network Provider Interface (NPI) . . . . 126
Restrictions . . . . . . . . . . . 126
Chapter 7. Client Security . . . . . . 127
Overview . . . . . . . . . . . . 127
Default connection settings . . . . . . 128
Security popups . . . . . . . . . 128
ECI security. . . . . . . . . . . . 129
EPI terminal security. . . . . . . . . 129
Password expiry management . . . . . 130
Network Provider Interface (NPI) . . . . 130
Signon capable and signon incapable
terminals. . . . . . . . . . . . . 131
Mainframe CICS servers . . . . . . 132
TXSeries and CICS OS/2 servers. . . . 134
CICS/400 servers . . . . . . . . . 134
Chapter 8. Performance . . . . . . . 135
Assessing system performance . . . . . 135
CICS Transaction Gateway configuration . . 136
Java considerations . . . . . . . . . 138
Other system factors . . . . . . . . . 138
Tracing . . . . . . . . . . . . . 139
Performance monitoring tools. . . . . . 140
Chapter 9. Operating the Gateway . . . 141
Before you start . . . . . . . . . . 141
Starting the Gateway. . . . . . . . . 141
Starting the Gateway with preset options 142

|
|
|
|
|
|
|
|
|
Starting the Gateway with user-specified
options . . . . . . . . . . . . 142
Stopping the Gateway . . . . . . . . 144
The CICS Transaction Gateway icons . . . 144
Running CICS Transaction Gateway as a
Windows service . . . . . . . . . . 146
Starting and stopping the service . . . 146
Startup options for the CICS Transaction
Gateway service . . . . . . . . . 146
CICS Transaction Gateway service and
console messages . . . . . . . . . 147
The ctgservice utility. . . . . . . . 147
Running as a Windows service under
Java 1.3.0 . . . . . . . . . . . 149
Client daemon service . . . . . . . 149
Administering your system . . . . . . 149
Setting the Gateway trace . . . . . . 150
Setting the JNI trace . . . . . . . . 150
Querying trace settings . . . . . . . 150
Parameters . . . . . . . . . . . 150
Chapter 10. Operating the Client daemon 153
The CICSCLI command . . . . . . . . 153
Running the Client daemon as a Windows
service . . . . . . . . . . . . . 153
Service controls . . . . . . . . . 154
Service startup parameters . . . . . . 155
Starting and stopping the service . . . 155
Starting the Client daemon service at
Windows startup . . . . . . . . . 155
The CICSCLI command . . . . . . . . 156
Starting the Client daemon. . . . . . 156
Starting connections with additional
servers . . . . . . . . . . . . 157
Stopping the Client daemon in a
controlled manner . . . . . . . . 157
Stopping the Client daemon immediately 157
Restarting the Client daemon in a
controlled manner . . . . . . . . 158
Restarting the Client daemon
immediately . . . . . . . . . . 158
Starting client tracing . . . . . . . 158
Specifying the trace components . . . . 158
Stopping client tracing . . . . . . . 158
Setting up security . . . . . . . . 158
Version information . . . . . . . . 159
Listing the connected servers . . . . . 159
Disabling the display of messages . . . 159
Enabling and disabling the display of
pop-up messages . . . . . . . . . 159
Displaying the command parameters . . 160
The CICSCLI command and applications 160
Alternative to CICSCLI.EXE . . . . . 160
CICSCLI command reference . . . . . . 160
Chapter 11. Terminal Emulation . . . . 167
Summary of Terminal Emulation commands 167
The CICSTERM command . . . . . . . 167
Using CICSTERM. . . . . . . . . 168
Stopping a terminal emulator . . . . . 169
CICSTERM and user exits . . . . . . 169
CICSTERM and RETURN TRANSID
IMMEDIATE . . . . . . . . . . 169
CICSTERM command reference . . . . . 169
Terminal emulator preferences . . . . . 172
The CICSPRNT command . . . . . . . 173
Using CICSPRNT . . . . . . . . . 174
CICSPRNT and user exits . . . . . . 175
CICSPRNT and RETURN TRANSID
IMMEDIATE . . . . . . . . . . 175
CICSPRNT command reference . . . . . 175
Chapter 12. Workload Manager . . . . 179
Workload Manager overview . . . . . . 179
Key concepts . . . . . . . . . . 180
What the Workload Manager needs to know 181
Load balancing algorithms . . . . . . . 183
The round-robin algorithm. . . . . . 183
The biasing algorithm . . . . . . . 183
Workload Manager failure recovery . . . . 184
Workload Manager implementation . . . . 184
ECI implementation . . . . . . . . 184
EPI implementation . . . . . . . . 185
Workload Manager installation . . . . . 185
Tracing the Workload Manager . . . . . 186
Workload Manager programming
requirements . . . . . . . . . . . 186
Chapter 13. The Terminal Servlet program 187
What is the CICS Transaction Gateway
Terminal Servlet? . . . . . . . . . . 187
Installing and configuring the Terminal
Servlet . . . . . . . . . . . . . 189
Configuring the Web server’s
CLASSPATH and PATH settings . . . . 190
Adding the Terminal Servlet to the Web
server’s configuration . . . . . . . 190
Configuring the servlet initialization
parameters . . . . . . . . . . . 190
Considering other configuration options 194
Contents v

|
Loading the Terminal Servlet . . . . . 195
Using the Terminal Servlet. . . . . . . 195
Connecting to CICS and starting a
transaction . . . . . . . . . . . 195
Invoking the Terminal Servlet . . . . . 195
What happens next? . . . . . . . . 197
Displaying screens and fields . . . . . 197
Sending the screen back to CICS. . . . 199
Setting the AID . . . . . . . . . 199
Disconnecting . . . . . . . . . . 200
Properties and parameters reference . . . 200
Servlet configuration properties . . . . 201
Page mapping properties . . . . . . 203
Request parameters . . . . . . . . 204
Displayable properties . . . . . . . 205
CICS Transaction Server for z/OS Web
Interface . . . . . . . . . . . . . 206
Chapter 14. Problem determination and
problem solving. . . . . . . . . . 207
Preliminary checks . . . . . . . . . 207
What to do next . . . . . . . . . 208
Problems with the Gateway daemon . . . 208
Messages . . . . . . . . . . . 208
Tracing . . . . . . . . . . . . 209
Diagnosing common problems: Gateway
daemon . . . . . . . . . . . . 212
Problems with the Client daemon . . . . 218
Messages . . . . . . . . . . . 218
Tracing . . . . . . . . . . . . 219
Diagnosing common problems: Client
daemon . . . . . . . . . . . . 227
Program support . . . . . . . . . . 236
Reporting problems . . . . . . . . 236
Documenting problems . . . . . . . 237
Locating and compiling information . . 238
Submitting the documentation . . . . 239
APARs and fixes . . . . . . . . . 239
Chapter 15. Migration . . . . . . . . 241
The configuration conversion tool . . . . 241
Using the conversion tool . . . . . . 242
Migrating from CICS Client Version 2 . . . 243
Migrating from CICS Universal Client, or
CICS Transaction Gateway, Version 3 . . . 243
TCP62 multiple server definitions . . . 243
Migrating from CICS Gateway for Java . . 244
Migrating from the CICS Internet Gateway 245
CICS Internet Gateway default settings 245
CICS Internet Gateway override settings 246
vi CICS Transaction Gateway: Windows Administration
|
|
|
|
|
|
|
|
CICS Internet Gateway actions 247
Administration functions . . . . . . 248
Migrating from CICS Gateway for Lotus
Notes . . . . . . . . . . . . . 248
EPI beans provided in earlier versions of the
CICS Transaction Gateway . . . . . . . 248
Appendix A. Data conversion between the
Client daemon and a CICS server . . . 251
Data conversion on Windows . . . . . . 251
Supported conversions . . . . . . . . 252
Appendix B. Hardware and software. . . 257
Hardware requirements. . . . . . . . 257
Supported software . . . . . . . . . 258
Operating systems . . . . . . . . 258
Web browsers . . . . . . . . . . 259
Telnet clients . . . . . . . . . . 260
JDK levels . . . . . . . . . . . 260
JSSE . . . . . . . . . . . . . 260
CICS Servers . . . . . . . . . . 261
Web servers. . . . . . . . . . . 261
Application servers . . . . . . . . 261
SNA communications . . . . . . . 261
TCP/IP communications . . . . . . 262
TCP62 communications . . . . . . . 262
Compilers and application development
tools . . . . . . . . . . . . . 262
Screen readers . . . . . . . . . . 263
Other tools . . . . . . . . . . . 263
GPL licence and copyright issues on
Linux . . . . . . . . . . . . . 263
The product library and related literature 265
CICS Transaction Gateway books . . . . 265
Sample configuration documents. . . . . 266
Redbooks . . . . . . . . . . . . 267
Other Useful Books . . . . . . . . . 267
CICS Transaction Server publications . . 267
Microsoft ® Windows Family publications 268
APPC-related publications . . . . . . 268
TCP62–related publications . . . . . 269
Obtaining books from IBM. . . . . . . 269
Accessibility . . . . . . . . . . . 271
Documentation . . . . . . . . . . 271
Installation . . . . . . . . . . . . 271
iKeyMan. . . . . . . . . . . . . 271
Samples . . . . . . . . . . . . . 271
Configuration tool accessibility . . . . . 271

|
|
|
|
|
Components . . . . . . . . . . 271
Keys . . . . . . . . . . . . . 272
Customizing colors and fonts . . . . . 274
Using help . . . . . . . . . . . 274
Task Guide . . . . . . . . . . . 274
Glossary . . . . . . . . . . . . 275
Index . . . . . . . . . . . . . 287
Notices . . . . . . . . . . . . . 295
Trademarks . . . . . . . . . . . . 296
Sending your comments to IBM . . . . 299
Contents vii

viii CICS Transaction Gateway: Windows Administration

About this book
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.
Summary of changes Read this for information on functional changes made in this
version of CICS Transaction Gateway.
Chapter 1, “Overview” Read this for an overview of CICS Transaction Gateway and
the functions it provides.
Chapter 2, “Planning
your installation”
Chapter 3,
“Installation”
Chapter 4, “Setting up
communication with
CICS servers”
Chapter 5,
“Configuration”
Chapter 6, “Network
Security”
Chapter 7, “Client
Security”
Chapter 8,
“Performance”
Chapter 9, “Operating
the Gateway”
Chapter 10,
“Operating the Client
daemon”
Chapter 12, “Workload
Manager”
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 network security protocols SSL and
HTTPS.
Read this for information on how to provide a userid 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 Gateway
daemon.
Read this for information on how to operate the Client
daemon of CICS Transaction Gateway.
Read this for information on how to use the Workload
Manager part of CICS Transaction Gateway to distribute
server workload.
© Copyright IBM Corp. 1996, 2002 ix

Chapter 13, “The
Terminal Servlet
program”
Chapter 14, “Problem
determination and
problem solving”
Chapter 15,
“Migration”
Appendix A, “Data
conversion between
the Client daemon
and a CICS server”
The product library
and related literature
Read this for information on how to use the Terminal Servlet
to access CICS 3270 applications using a Web browser.
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.
Read this for information on the conversion of character data
as it passes between the Client daemon of CICS Transaction
Gateway and a CICS server.
Read this for information on the CICS Transaction Gateway
product library and related literature, and the various forms
in which it is available.
Accessibility Read this for information on the accessibility features of CICS
Transaction Gateway.
Notices Read this for important information on the availability of
IBM products and service in different countries, and also on
issues concerning patents, licenses, and trademarks.
Sending your
comments to IBM
Read this for information on how to send your comments to
IBM.
Conventions and terminology used in this book
A number of parts, both internal and external to the CICS Transaction
Gateway, are used when creating a business solution using the product.
Figure 1 on page xi shows some of the possible scenarios you will encounter,
and the terminology used in each case.
x CICS Transaction Gateway: Windows Administration

Distributed platforms running in remote mode
Java client
application
z/OS running in local mode
Java client
application
Gateway
classes
Gateway
classes
CICS
server
Gateway
daemon
Distributed platforms running in local mode
Java client
application
Gateway
classes
Client
daemon
Distributed platforms running non-Java applications
Client
application
Client
daemon
z/OS running in remote mode
Java client
application
Gateway
classes
CICS
server
Gateway
daemon
Client
daemon
CICS
server
CICS
server
Figure 1. CICS Transaction Gateway uses, with their associated terminology
CICS
server
The following explains the terms used in Figure 1:
Gateway daemon
Used only in remote mode, the Gateway daemon listens on protocols
defined in CTG.INI for gateway requests from remote Java client
applications. It issues these requests to the Client daemon on
distributed platforms, and directly to CICS over the EXCI on z/OS ® .
The Gateway daemon runs the protocol listener threads, the worker
threads and the connection manager threads. It uses the GATEWAY
section of CTG.INI (and on z/OS the ctgenvvar script) for its
configuration.
Client daemon
The Client daemon (process cclclnt) exists only on distributed
platforms. 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.
About this book xi

Gateway classes
The interface for Java Client applications to connect to the Gateway
daemon. The Gateway classes, which are supplied with the CICS
Transaction Gateway, must be in the classpath for Java Client
applications to run.
Client application
A user application, written in a supported programming language
other than Java, that communicates directly with the Client daemon.
Java Client application
A Java application, servlet or applet that communicates with the
Gateway classes.
Installation path
The term is used in file paths to represent the directory where
you installed the product. The default installation locations for each operating
system are shown in Table 1:
Table 1. Default CICS Transaction Gateway installation locations
Operating System Default installation location
Windows ®
c:\Program Files\IBM\IBM CICS Transaction Gateway
AIX ®
/usr/lpp/ctg
Linux, HP-UX, Solaris /opt/ctg
z/OS A ctg subdirectory of the directory from which the
installation was run. For example, if the CICS
Transaction Gateway was installed by the command
ctginstall in the /usr/lpp directory, the
is /usr/lpp/ctg
Programming language specific
The term C refers to both the C and C++ programming languages.
Operating system specific
Unless otherwise specified, the term Windows refers to Windows NT ® ,
Windows 2000, and Windows XP.
The term Windows 2000 Terminal Server means a server with the Terminal
Services feature installed.
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.
Syntax notation
The syntax of commands is shown in a standard way. This syntax, commonly
known as railroad syntax, is described in Table 2 on page xiii. You interpret the
syntax by following the arrows from left to right, and from top to bottom,
xii CICS Transaction Gateway: Windows Administration

along the main path line.
Table 2. Command syntax conventions
Symbol Meaning
Required items appear on the main path line.
►► AB ►◄
►► A
B
C
►►
►►
►►
A B
A
B
C
A
B
C
►► ▼ A
►► ▼
A
B
C
B
►◄
►◄
►◄
►◄
►◄
►◄
Punctuation and uppercase
characters
Lowercase characters appearing
like this
If there is more than one required item to choose
from, the items are stacked vertically. This is a set of
alternatives—one of which you must specify.
Optional items appear below the main path line.
If there is more than one optional item to choose
from, the items are stacked vertically below the
main path line. This is a set of alternatives—one of
which you may specify.
If one item in a set of alternatives is the default, this
item appears above the main path line and all other
items are stacked vertically below the line.
An arrow returning to the left above items on the
main path line means that the items can be repeated.
Such items may be either required or optional.
An arrow returning to the left above a set of items
means that more than one item can be selected or
that a single item can be repeated.
Note: For CICS, unless otherwise stated, this
representation means only that more than one item
can be selected.
Code exactly as shown.
Code your own text, as appropriate. For example,
with FILE(name) you must specify FILE and ()
unchanged, but are free to specify any valid text
string for the name of your file.
About this book xiii

xiv CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Summary of changes
The following functional changes have been made for CICS Transaction
Gateway Version 5.0:
v The Windows XP operating system is supported.
v The Binary Trace Formatter utility has been enhanced to format SNA and
MPTN data structures within TCP62 data flows. See “Formatting the binary
trace file” on page 222.
v COBOL is supported.
v A systems administration function allows you to set options for Gateway
and JNI traces, to start and stop these traces, and to query trace settings;
see “Administering your system” on page 149. Using the CTG_JNI_TRACE
environment variable to enable JNI tracing is supported only for migration
purposes.
v The way that CICS Transaction Gateway writes log messages has changed:
– Each message entry begins with the current date in the format
month/day/year.
– CICS Transaction Gateway writes error and warning messages to
standard error (stderr), and information messages to standard output
(stdout); see “Messages” on page 208.
– A new gateway configuration setting, Log client connections and
disconnections, controls whether CICS Transaction Gateway writes a
message each time that a client application program connects to, or
disconnects from, the Gateway daemon. See “Log client connections and
disconnections” on page 61.
v Some beans that were previously provided as part of the CICS Transaction
Gateway product are now, instead, included with the set of sample
programs. See “EPI beans provided in earlier versions of the CICS
Transaction Gateway” on page 248 for details.
v Java Secure Socket Extension (JSSE) is supported.
This gives 128 bit encryption capability and is IBM’s recommended solution
for SSL. For compatibility with previous versions of CICS Transaction
Gateway, this version supports both JSSE and SSLight. However, support
for SSLight might be removed in a future release.
This edition replaces SC34-5932.
Vertical lines at the left side of the page indicate material that is new to this
edition.
© Copyright IBM Corp. 1996, 2002 xv

xvi CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
Chapter 1. Overview
IBM CICS Transaction Gateway provides secure, easy access from Web
browsers and network computers to CICS applications, using standard
Internet protocols in a range of configurations. It is a robust and scalable
complement to a Web 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. 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
the Windows and UNIX ® operating systems, CICS Transaction Gateway can
access many different types of CICS server. On z/OS CICS Transaction
Gateway can access only CICS Transaction Server for z/OS. See “Supported
software” on page 22 for information on supported operating systems and
CICS servers.
On the Windows and UNIX operating systems, 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 3). On z/OS, CICS
Transaction Gateway can route only ECI requests, and has no Client daemon.
© Copyright IBM Corp. 1996, 2002 1

Overview
Network
computer
Java-enabled
browser
Figure 2 shows how a web client can access CICS programs and data. Note
that the CICS Transaction Gateway is shown as installed on a Web server
machine. This is necessary only if you are using the CICS Transaction
Gateway with Java applets or servlets.
HTTP
HTTPS
SSL
TCP
HTTP
Figure 2. CICS Transaction Gateway
Server machine
Web server
CICS
Transaction
Gateway
Java application
CICS
server
Communication between CICS Transaction Gateway and the client application
uses the following protocols:
v Transmission control protocol/Internet protocol (TCP/IP) sockets
v Hypertext Transfer Protocol (HTTP)
v Secure Sockets Layer (SSL)
v HTTP over SSL (HTTPS)
TCP/IP sockets and SSL provide an efficient method of communication for
intranet applications. Where firewalls exist, HTTP, and its secure alternative
HTTPS, are effective communication protocols for internet applications. See
“Network security” on page 6.
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.
2 CICS Transaction Gateway: Windows Administration
Local
EPI
ESI
ECI

What CICS Transaction Gateway provides
What CICS Transaction Gateway provides
A Gateway daemon
For security reasons, this is usually resident on a Web server workstation. It
communicates with CICS applications running on CICS servers through ECI,
EPI, or ESI.
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 applications, or Java servlets, and
the Gateway daemon.
v allow client applications to communicate with transactions on a server and
to handle 3270 data streams
v allow your applications to use the SSL network security protocol
J2EE resource adapters
Use these to provide a J2EE-compliant interface to CICS for your 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 between the Gateway and CICS
servers” on page 26. 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 22.
The way the client 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 51.
The external access interfaces (ECI, EPI, ESI)
The external access interfaces allow non-CICS applications to access and
update CICS resources by initiating CICS transactions, or by calling CICS
programs. When used in conjunction with the CICS communication facilities,
they enable 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.
These APIs are provided for both Java and non-Java programming languages.
Chapter 1. Overview 3

What CICS Transaction Gateway provides
External Call Interface (ECI)
The ECI enables a non-CICS client 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 non-CICS client 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)
ESI enables non-CICS client applications to invoke services provided by APPC
password expiry management (PEM). This allows non-CICS applications to verify
that a password matches that recorded by an external security manager (ESM)
for a specified user ID. ESI also allows you to change passwords.
For more information on the external access interfaces, see CICS Transaction
Gateway: Programming Guide and CICS Transaction Gateway: Programming
Reference.
A Terminal Servlet
This allows you to use a Web browser as an emulator for a 3270 CICS
application running on any CICS server. The Terminal Servlet can be used
with a Web server, or servlet engine. The Terminal Servlet provides an
alternative to using EPI. For information on supported Web servers, refer to
“Supported software” on page 22.
Additional functions
3270 terminal emulation (CICSTERM)
CICS 3270 terminal emulation enables a 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 (with some exceptions, see Table 5 on
page 27) are autoinstalled at most CICS server systems, and do not have to be
predefined at the server.
4 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Additional functions
3270 printer support (CICSPRNT)
CICS 3270 printer support allows you to define a printer terminal on a
Gateway system. This enables CICS applications running on a server to send
output to a printer attached to CICS Transaction Gateway.
You can send output to a physical printer attached, for example, to the LPT1
port, 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 5 on page 27 for information on which CICS servers currently support
CICS 3270 emulation and hence CICS 3270 client printer support.
CICS Transaction Gateway: local control
Commands or icons are provided to:
v Control the Gateway daemon
You can:
– Specify the TCP/IP port on which the CICS Transaction Gateway listens.
– Specify an initial number of ConnectionManager threads
– Specify a maximum number of ConnectionManager threads
– Specify an initial number of Worker threads
– Specify a 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 hostnames 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
– 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
Chapter 1. Overview 5

|
|
|
|
|
Additional functions
– 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.
CICS Transaction Gateway: remote control
You can:
v Set the trace for the Gateway daemon
v Set JNI trace
v Query trace options
Network security
CICS Transaction Gateway provides comprehensive support for secure
communication, which is critical to successful Internet operation. The secure
network protocols SSL and HTTPS allow your 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 103; the following sections summarize
the functions provided by SSL and HTTPS.
The characteristics of secure communication are:
Confidentiality
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.
Integrity
Messages are not altered during transmission.
Integrity guarantees that the message you sent reaches the recipient
intact. Encryption and digital signatures ensure integrity.
Accountability
6 CICS Transaction Gateway: Windows Administration

Network security
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.
Authenticity
You know who you are talking to and 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:
1. 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.
2. 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
Chapter 1. Overview 7

Network security
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 10.
Digital signatures and digital certificates
A digital signature is a unique, mathematically computed, signature that
ensures accountability.
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 certification 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.
8 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
Network security
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 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 certification authority
If you plan to conduct commercial business on the Internet, buy a server
certificate from a CA such as VeriSign or Thawte.
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 may choose to
allow access to only a carefully controlled group of key people within your
intranet.
Your key people should have browsers, such as Netscape Navigator, 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 103 for more information on
obtaining digital certificates.
KeyRings and KeyStores
Digital certificates, public keys, private keys, and trusted root keys are kept in
special types of file which the security protocols can use:
v SSLight, System SSL, and HTTPS use Java class files called KeyRings
v Java Secure Socket Extension (JSSE) uses files called KeyStores
CICS Transaction Gateway uses KeyRings and KeyStores to hold information
about certificates and keys on both the SSL server and SSL clients. See
Chapter 1. Overview 9

Network security
“SSLight” on page 104, and “Java Secure Socket Extension (JSSE)” on page 114,
for information on how to create these files. The SSL and HTTPS protocols
require access to these files to establish secure connections. See “Configuring
CICS Transaction Gateway for SSL and HTTPS” on page 124 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 11 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
10 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
Client Server
Client issues secure session request
(https.//someserver.org/somedata.html)
Server sends X.509 certificate containing server’s public key
Client authenticates certificate against list of known CA’s
(If CA is unknown browser can give user option to accept certificate at user’s risk)
Client generates random symmetric key and encrypts it using server’s public key
Client and server now both know the symmetric key
and encrypt end-user data using symmetric key for duration of session
Figure 3. SSL handshaking with server authentication
Network security
CICS Transaction Gateway supports the following implementations of SSL:
SSLight
An implementation of SSL that is written in pure Java.
This protocol is supported for compatibility with previous
versions of CICS Transaction Gateway. However, support for
SSLight might be removed in a future release.
JSSE
Another Java implementation, that provides support for 128
bit encryption.
IBM recommends that you use JSSE in preference to SSLight.
See “Migration from SSLight” on page 114, for more
information.
System SSL
Chapter 1. Overview 11

Network security
This implementation, which is written in native code, is
supported only for SSL servers on z/OS. It supports hardware
encryption technology available to the z/OS operating system.
HTTPS
HTTPS is a protocol that combines SSL and HTTP, and is used for handling
secure transactions. You specify https:// as an anchor in HTML documents
that link to documents protected by SSL. A client user can also open a URL by
specifying https:// to request an SSL-protected document.
Because HTTPS and HTTP are different protocols, and usually use different
ports (443 and 8080 respectively), you can run both SSL and non-SSL requests
at the same time. This allows you to provide information to all users using no
security, and specific information only to browsers which make secure
requests. This is how retail companies on the Internet allow users to look
through the merchandise without security, but then fill out order forms and
send their credit card numbers using security.
Security exits
CICS Transaction Gateway provides exits that enable the user to define
security operations such as public key encryption. They may also be used for
data compression. Some example source files are provided in this directory:
\samples\java\com\ibm\ctg\samples\security
Java technology
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 book.
This section discusses the Java language, including the types of program that
can be developed, and the security implications.
The Java language
Java is an interpreted object-oriented language, similar to C++. It can be used
to build programs that are independent of operating systems in both source
and object form. Its unique operational characteristics, which span Web
browsers as well as Web servers, enable new and powerful functions in
Internet applications.
To achieve operating system independence, the Java language allows no
operations that are dependent on specific operating system. Also, it excludes
some C++ functions such as a preprocessor, operator overloading, multiple
inheritances, and pointers. All Java programming is encapsulated within
classes, and the Java Development Kit (JDK) includes special classes that are
12 CICS Transaction Gateway: Windows Administration

|
|
|
|
critical to assuring operating system independence, including GUI functions,
input/output functions, and network communications.
The Java compiler produces an intermediate bytecode format that is machine
independent. This, in turn, is processed at run time by a Java interpreter. The
interpreter also inspects the bytecode at run time to ensure its validity and
safety to the machine environment. Because of the isolation the Java
interpreter provides, it is sometimes referred to as a Java Virtual Machine
(JVM).
The Java language can be used to construct Java servlets, Java applets, and Java
applications.
Java applets
Java applets are supported for compatibility with previous versions of 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 servlets
Java servlets are small Java applications that run on a Web server machine,
unlike Java applets, which are downloaded to a Web browser.
Java servlets have become popular as a replacement for CGI (Common
Gateway Interface) programs. The advantage of Java servlets over CGI
applications is that they can execute more quickly since they are invoked as
threads in a daemon process, meaning that they are persistent in memory and
can fulfill multiple requests.
Note that servlets must ensure references to the gateway objects are
thread-safe.
Java technology
Java applications
A Java application is a program that executes locally on a computer. It has
operating system dependent capabilities in addition to those of an applet. It
can access local files, create and accept general network connections, and call
native C or C++ functions in machine-specific libraries.
Java applications can use the CICS-provided Java classes to perform
transaction processing in CICS systems. They can use the JavaGateway class
to establish two kinds of connection:
v A network gateway connection is a connection across a network to a CICS
Transaction Gateway.
v A local gateway enables a Java application to communicate directly with a
CICS Transaction Server, without the need for a network.
Chapter 1. Overview 13

Java technology
JavaBeans
When the connection between the application and the CICS Transaction
Gateway has been established, an application can use the ECIRequest class,
for example, to do transaction processing.
The JavaBeans API, developed by Sun Microsystems, allows you to write
component software in Java. Components are self-contained, reusable software
units that you can build into servlets using visual application builder tools.
Any JDK Version 1.1-compliant browser or tool supports JavaBeans.
JavaBeans components are called beans. Most builder tools allow you to
maintain beans in a palette or toolbox. You can select a particular bean from
the toolbox, drop it onto a form, modify its appearance and behavior, and
define how it interacts with other beans. You can build your selected bean
and other beans into a servlet, or new bean, without actually writing any
code. For more information on JavaBeans, see the Sun Web site
(www.java.sun.com).
The CICS Transaction Gateway provides EPI Java bean samples based on
high-level EPI interfaces. These beans allow you easily to create Java
programs that access data from existing CICS 3270 applications, without any
programming. Using a bean composer tool, you can quickly and easily create
new Java front-ends that can connect to CICS, run transactions, display data
from 3270 screens, and send user input back to the CICS server. For more
information, see the CICS Transaction Gateway: Programming Guide.
Firewalls
A current design consideration in the use of Java applet communication is the
impact of firewalls. This is the term given to a configuration of software that
prevents unauthorized traffic between a trusted network and an untrusted
network. Firewalls are put in place to protect company assets from outside
intrusion, but they can also limit legitimate communications. Firewalls have
two functions:
1. To restrict access to a server by outside users - inbound restrictions
2. To limit the ability of users inside a firewall to perform certain network
functions outside their firewall - outbound restrictions.
A CICS Transaction Gateway configuration is well suited to avoid problems in
the first area since the Gateway processor can be placed outside the firewall
and be connected through the firewall to the CICS server. Outbound firewalls
that users may have to contend with can be a problem. A large company
might use a firewall to limit the types of connections and protocols that can
be used.
The use of Java on an intranet (a local implementation of the Internet) works
very well since firewalls are typically not a factor. If you are designing
14 CICS Transaction Gateway: Windows Administration

Java technology
applications to run over the Internet (rather than an intranet), determine
whether your potential users are behind firewalls. If so, consider alternative
processing for those users, such as executing the Java code as a Java servlet
on the Web server. Also consider using HTTP and HTTPS protocols supported
by CICS Transaction Gateway, see “Authentication using SSL” on page 10 and
“HTTPS” on page 12.
Web servers
A Web server is a software program that responds to information requests
generated by Web browsers. When a request from a browser is received, the
Web server processes the request to determine the action to take:
v Return the requested document.
v Deny the request.
v Pass the request through for further processing by an external application.
The request might be, for example, to a database to perform a search
request, or to a more dynamic form of information delivery such as Lotus ®
Domino .
Communication between a Web server and an external application is
transparent; you need to know only the URL of the Web server to direct a
request to it. Also, all Web servers can handle requests from many browsers
concurrently.
Specialized servers can also be configured to limit access to a restricted set of
users, or to provide security for purchase of goods or services.
Web servers exist for almost every operating system and are available from
many suppliers. For information on the Web servers supported by CICS
Transaction Gateway, see “Supported software” on page 22.
The J2EE resource adapters
An API in the CICS Transaction Gateway allows Java programmers to take
advantage of features provided in J2EE-compliant runtime environments (e.g.
IBM WebSphere Application Server). The J2EE resource adapter defines a
standard architecture for connecting the Java 2 Platform, Enterprise Edition
(J2EE) to heterogeneous Enterprise Information Systems (EIS) such as CICS.
The resource adapter architecture defines a set of scalable, secure, and
transactional mechanisms that enable the integration of EISs with application
servers and enterprise applications.
A proprietary application server, such as IBM WebSphere, can be extended to
support the resource adapter architecture, and is then assured of a seamless
Chapter 1. Overview 15

Introduction
connectivity to multiple EISs. Similarly, a vendor provides a standard resource
adapter that can connect any application server that supports the resource
adapter architecture to an EIS.
The resource adapter architecture defines a Common Client Interface (CCI) for
EIS access. The CCI defines a client API for interacting with heterogeneous
EISs. The resource adapter architecture enables a vendor such as IBM to
provide a standard resource adapter to allow access to its product. This
resource adapter connects 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 which are provided.
The samples.txt file, in the \samples subdirectory, provides
additional information on the J2EE sample programs.
How CICS Transaction Gateway accesses CICS
This section describes how CICS Transaction Gateway allows Java servlets to
access CICS programs and data.
1. The Web server loads and initializes the servlet. This could be when the
Web server starts, or when the first request is made to the servlet by the
Web browser or network computer.
2. The servlet creates a JavaGateway object to connect to the CICS
Transaction Gateway. This establishes communication between the
browser and the long running Gateway daemon process using Java’s
sockets protocol.
3. When a HTTP request from the Web browser or network computer
invokes the servlet, the Web server calls its Service method with details
of the request.
4. The servlet creates an ECIRequest, EPIRequest, orESIRequest object,
that contains ECI, EPI, or ESI calls, and sends it to the Gateway daemon
using the JavaGateway.flow method.
5. The Gateway daemon receives, and unpacks the request. The Client
daemon makes corresponding ECI, EPI, or ESI calls to the CICS server.
6. The CICS server processes the calls, including verification of the userid
and password if required, and passes control and user data to the CICS
application program.
7. When the CICS application program has finished processing, it returns
control and data to CICS.
8. The CICS server returns control and data to the Client daemon.
16 CICS Transaction Gateway: Windows Administration

9. The Gateway daemon packs these results and returns them to the Java
servlet.
10. When the servlet receives the results, it generates a HTTP response to
return to the Web browser.
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 clients. The threading model uses the following objects:
ConnectionManagers
A ConnectionManager manages all the connections from a particular Java
client. When it receives a request, it allocates a Worker thread from a pool of
available Worker threads to execute the request.
Workers
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.
You can set both the initial and maximum sizes of the resource pools for these
objects; see “Configuring CICS Transaction Gateway settings” on page 58 for
information on setting configuration parameters. You can also specify these
limits when you start the CICS Transaction Gateway, see “Starting the
Gateway with user-specified options” on page 142.
Table 3 shows thread limits that should be considered when setting the
number of Connection Manager and Worker threads on the various operating
systems:
Table 3. Thread limits on CICS Transaction Gateway operating systems
Operating
system
System-wide limit of
the maximum number
of threads
z/OS This may be restricted
by the total number of
MVS ® Task Control
Blocks (one is created
per UNIX System
Services thread)
How CICS Transaction Gateway accesses CICS
Process limit of the number of threads
Governed by the UNIX System Services
parameters: MAXTHREADS and
MAXTHREADTASKS
Windows No limit Limited by the amount of virtual memory
available for the process (by default a
thread has 1M of stack meaning that 2028
threads can be created per process)
Chapter 1. Overview 17

The CICS Transaction Gateway: threading model
Table 3. Thread limits on CICS Transaction Gateway operating systems (continued)
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 Configurable Kernel
Parameters in the SAM utility)
1024 (refer to your LinuxThreads
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
book.
The threading model is illustrated in the following figures:
Figure 4. CICS Transaction Gateway threading model for TCP/IP and SSL. These protocols have a persistent socket.
18 CICS Transaction Gateway: Windows Administration

CICS Transaction Gateway and object request brokers
Figure 5. CICS Transaction Gateway threading model for HTTP/HTTPS. These protocols do not have a persistent
socket.
CICS Transaction Gateway and object request brokers
Some Web servers contain an object request broker (ORB) that conforms to the
Object Management Group’s (OMG) Common Object Request Broker
(CORBA) standard. If you have such a Web server, you can develop servlet
objects that can be invoked from a remote browser using the CORBA Internet
InterORB Protocol (IIOP). IIOP is transmitted to the browser using HTTP.
Workload management
CICS Transaction Gateway provides a load balancing facility that allows the
transaction workload to be distributed across multiple CICS regions or CICS
servers. For more information see “Configuring the Workload Manager” on
page 84.
Chapter 1. Overview 19

20 CICS Transaction Gateway: Windows Administration

Chapter 2. Planning your installation
This chapter helps you to plan the installation of the CICS Transaction
Gateway by listing the hardware and software that you need. For information
about hardware and software requirements on all supported operating
systems, see Appendix B, “Hardware and software” on page 257. The CICS
servers to which CICS Transaction Gateway can connect are also listed.
The Chapter consists of the following topics:
“Hardware requirements” on page 22 Read this for information about the
hardware you need to run your CICS
Transaction Gateway (processor type,
memory, disk space).
“Supported software” on page 22 Read this for information about the
software products that are supported for
use with your CICS Transaction Gateway.
“CICS server PTF requirements” on
page 25
“Communication between the Gateway
and CICS servers” on page 26
Read this for information about APARs
and PTFs (service updates) for CICS
servers.
Read this for information about the
communications protocols you can use to
connect to your CICS servers.
“Server Code page support” on page 28 Read this for information about data
conversion between the CICS Transaction
Gateway and CICS servers.
If you are using an earlier version of the product, or a CICS Universal Client,
see Chapter 15, “Migration” on page 241 for a discussion of migration issues.
See the product readme file for any late changes to hardware and software
requirements.
If you are installing from CD, the readme file is README.WIN in the root
directory.
If you have 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.
© Copyright IBM Corp. 1996, 2002 21

Hardware requirements
Hardware requirements
Table 4. Hardware requirements on Windows systems
Processor Any processor capable of running the appropriate
operating system and other prerequisite software.
Network adapters To connect workstations to the LAN, you need a
suitable adapter such as an ethernet adapter.
Memory At least 64 MB.
Disk space You need 30 MB of free disk space for your CICS
Transaction Gateway (including documentation in US
English only).
Supported software
The following products are supported.
You need a further 30 MB for temporary files used
during installation. At least 12 MB of this must be on
your system partition.
Operating systems
CICS Transaction Gateway is supported on the following operating systems:
v Windows XP Professional
v Windows 2000 Professional with a minimum of Service Pack 1
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a
minimum of Service Pack 1
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a
v Windows NT Server V4.0 with a minimum of Service Pack 6a.
Notes:
– Windows NT 4 Terminal Server is not supported
– The setting of multiple user interface languages, under Windows
2000 MultiLanguage Version, is not supported.
– If you plan to run CICS Transaction Gateway under load, and
using remote protocols, it is strongly recommended that you use
a server version, rather than a workstation version, of Windows.
See “ConnectFailed exceptions when running under load” on
page 216, for more information.
Web browsers
v HTML/HTTP functions: Any browser that supports HTML V1.0 should
work with the product.
22 CICS Transaction Gateway: Windows Administration

v Java Functions: Any JDK 1.1 compliant Web browser should work with the
product.
The CICS Transaction Gateway is supported with the following browsers:
v Microsoft ® Internet Explorer 5.0, 5.5 and 6.0
v Netscape Communicator 4.7 and 6.2
Note: Applets running within the JVM supplied with the Netscape
Communicator browser fail to make successful connections with the
CICS Transaction Gateway. Message number CCL6652E is returned to
the applet. Currently there is no solution to this problem.
Java applets are supported for compatibility with previous versions of
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.
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 going in
as. Currently there is no solution to this problem.
JDK levels
CICS Transaction Gateway supports JDK levels 1.3 and 1.3.1 at the following
minimum service levels:
v IBM Java SDK 1.3 (service release 6)
JSSE
Supported software
CICS Transaction Gateway supports JSSE in the the following environments:
v Standard Java runtime environment (JRE).
Only the IBM JSSE is supported:
– Install the JSSE package supplied with CICS Transaction Gateway
v WebSphere Application Server:
All supported levels have built in JSSE support.
CICS Transaction Gateway does not support the use of JSSE with applets.
CICS Servers
A CICS server runs real-time multi-user applications and manages the
associated resources and data. CICS Transaction Gateway is supported with
the following servers:
v CICS Transaction Server for z/OS V2.2
Chapter 2. Planning your installation 23

|
|
|
|
|
Supported software
v CICS Transaction Server for z/OS V2.1 (with APAR PQ30168, for signon
capable terminals, applied)
v CICS Transaction Server for z/OS V1.3 with APAR PQ30168, for signon
capable terminals, applied.
v CICS for MVS/ESA V4.1, with communication through SNA. (with APAR
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for
EPI emulation. APAR PN79262 is needed for DBCS support.
v CICS for OS/400 ® V4.4
v CICS Transaction Server for OS/2 ® V4.1 with CSD 3
v CICS Transaction Server for VSE/ESA 1.1.0 (with APAR PQ30170, for
signon capable terminals, applied), or a minimum service level of 1.1.1
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)
v TXSeries V5.0 (Windows, AIX)
Web servers
Any web server that is supported by your application server should work
with the product.
Application servers
The CICS Transaction Gateway is supported with the following:
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,
AIX and Solaris.
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.
SNA communications
Customers wishing to use SNA communications should install one of the
following products:
Windows operating systems
Any one of:
v IBM eNetwork Communications Server V6.1, with a minimum of
service level 1
v IBM eNetwork Personal Communications V5.0, with a minimum of
service level 2
v IBM eNetwork Personal Communications V5.5
v Microsoft SNA Server V4.0 with a minimum of SP4
TCP/IP communications
TCP/IP support is provided by the operating system.
TCP62 communications
TCP62 support is provided by CICS Transaction Gateway.
24 CICS Transaction Gateway: Windows Administration

|
|
|
|
Compilers and application development tools
CICS Transaction Gateway is supported with the following compilers and
application development tools:
Windows
v IBM VisualAge ® COBOL V3.0
v Microsoft Visual C++ V6.0
v Microsoft Visual Basic V6.0
v Microsoft Visual Basic Script (VBScript) V5.0
Note: The CICS Transaction Gateway does not support use of the COM
libraries with Microsoft Transaction Server (MTS), or the MTS
component of COM+.
Screen readers
The CICS Transaction Gateway is supported with JAWS.
Other tools
These tools are available for viewing the PDF online documents:
v Adobe Acrobat Reader V5.0
CICS server PTF requirements
Supported software
See the README file for the latest details on APARs and PTFs applicable to
the CICS Transaction Gateway.
Terminal Signon capability
CICS Servers require APAR fixes to support the terminal signon capability
function available in this release; see “Supported software” on page 22 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 on CICSTERM,
the installed terminal will give unpredictable results.
Timeout support
To provide complete support for timeouts, if you are using any TXSeries or
Transaction Server on UNIX and Windows operating systems, it must include
the appropriate PTF level; see “Supported software” on page 22 for details.
If the server does not have the required APAR applied and the ’-a’ option is
not specified on CICSTERM, this happens:
v The CICS Transaction Gateway displays the message: CCL7053E Errors
found while communicating with server
v CCL3105 Inbound CICS datastream error (CTIN, 4, 0) is written to
CICSCLI.LOG
Chapter 2. Planning your installation 25

|
|
|
|
|
|
|
|
|
|
|
|
Supported software
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 between the Gateway and CICS servers
You can use these protocols to communicate with CICS servers:
TCP/IP Transmission Control Protocol/Internet Protocol (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 Systems Network
Architecture (SNA) flows over an IP network.
Local Named Pipe
TXSeries (Version 4.3 or later) for Windows NT can use the
Local Named Pipe protocol to communicate with a CICS
Transaction Gateway that is on the same computer. This
provides a fast communications method independent of any
network protocol.
The protocols that you can use for the various client/server connections are
shown in Table 5 on page 27. This table lists the protocols that you can use to
connect your CICS Transaction Gateway to your CICS server. It also shows
whether ECI, EPI emulation, and Autoinstall are supported for your
combination of CICS server and CICS Transaction Gateway operating system.
26 CICS Transaction Gateway: Windows Administration

Table 5. 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. Otherwise, *
means supported on Windows and all UNIX operating systems; V means not supported.
SERVER TCP/IP SNA TCP62 ECI
CICS for MVS/ESA
V4.1
CICS for OS/400
V4.4
CICS Transaction
Server for OS/2 V4.1
CICS Transaction
Server for z/OS V1.2
and V1.3
CICS Transaction
Server for VSE/ESA
V1.1.0 and V1.1.1
V
*
*
V
V
CICS/VSE V2.3 V
TXSeries V4.2
(HP-UX)
TXSeries V4.3 (AIX,
Solaris, Windows )
*
*
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
* *
EPI
Emulation
See note
AIX
HP-UX
Solaris
Windows
ESI
*
* * * *
V * * V
* *
V *
V *
Windows
AIX
HP-UX
Solaris
Windows
AIX
HP-UX
Solaris
AIX
HP-UX
Solaris
Windows
V * * V
V * * V
Note: EPI always incorporates CICS 3270 terminal emulation and CICS 3270
client printer support.
All servers support autoinstall. This means that you do not need to predefine
the client to the CICS server; control table definitions are automatically
created for the client at the CICS server. For CICS/VSE, autoinstall is possible
via LU 6.2 single session only. This restriction does not affect CICS Transaction
Server for VSE/ESA.
Restrictions on CICS for OS/400
The following restrictions apply:
v DBCS languages are not supported.
Communication protocols
*
Chapter 2. Planning your installation 27
V
V

|
|
|
|
|
|
|
Communication protocols
v Signon 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 5 some protocols can be used only for certain types of
client/server connection.
If you need to connect different types of networks, for example, Token Ring
and Ethernet networks, consider using TCP/IP.
TCP62 allows access to CICS Transaction Server for z/OS over a TCP/IP
network. Partner LU62 applications can communicate without complex SNA
configuration definitions on the client, and without any changes to the LU62
applications on the client or server. If you require easy client access to CICS
Transaction Server for z/OS over your TCP/IP network, use the TCP62
support. For information on configuring TCP62, see “TCP62 configuration” on
page 42.
Server Code page support
Some CICS servers do not support all of the code pages that are supported by
the CICS Transaction Gateway.
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 between the Client daemon
and a CICS server” on page 251, the CICS server documentation, and the
Redbook CICS Transaction Gateway V3.1 The WebSphere Connector for CICS.
28 CICS Transaction Gateway: Windows Administration

|
|
Chapter 3. Installation
This chapter describes how to install the CICS Transaction Gateway. It consists
of the following:
“Choosing what to install” Read this to find out what you can install.
“Microsoft Windows Installer Service” on
page 30
“Installing the CICS Transaction
Gateway” on page 31
Read this for information on the
Microsoft Windows Installer Service.
Read this for detailed instructions on how
to install your CICS Transaction Gateway.
“Actions after installation” on page 36 Read this for information on what you
should do after you have installed the
CICS Transaction Gateway.
“Maintaining or uninstalling the CICS Read this for information on how to:
Transaction Gateway” on page 37 v Change installed components
v Repair installation errors
v Uninstall the CICS Transaction
Gateway
“Updating the CICS Transaction
Gateway” on page 39
Read this to learn how to get updates and
fixes for the product.
Choosing what to install
You can choose either a complete or custom installation.
Complete
Installs all components:
v Program files
v Development kit
v Programming samples (installed to \samples\)
v Toolkit
v Documentation
into the default installation directory (see Table 1 on page xii).
Custom
Allows you to select which components to install, and specify the target
drive and directory.
All shortcuts are created in the IBM CICS Transaction Gateway folder in the
Start –> Programs menu for all users.
© Copyright IBM Corp. 1996, 2002 29

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Choosing what to install
You can also choose to install IBM’s runtime environment for Java. You need
Java to run the full CICS Transaction Gateway product, and the configuration
tool. You do not need it to run only the Client daemon.
Microsoft Windows Installer Service
CICS Transaction Gateway supports the Microsoft Windows Installer Service,
which offers the following features:
v If the installation fails, the Microsoft Windows Installer Service can restore
your system to its original state. However, it cannot restore files that have
been removed during an upgrade from an earlier version.
v If CICS Transaction Gateway becomes corrupted, the Microsoft Windows
Installer Service can repair the problem. Follow the instructions in
“Maintaining or uninstalling the CICS Transaction Gateway” on page 37.
v You can add or remove components, or remove the whole installation.
Upgrading
Consult your Windows product documentation for full details of the Microsoft
Windows Installer Service.
Remove any beta versions of the product before installation.
Currently installed product Upgrade type
CICS Universal Client v5.0 No upgrade. Uninstall the product before
continuing.
CICS Transaction Gateway v4.00, 4.01 and Normal upgrade.
4.02
CICS Transaction Gateway v3 Copies the relevant INI files before
uninstalling the older version and then
installing CICS Transaction Gateway
Version 5.0
CICS Universal Client v3 Copies the relevant INI files before
uninstalling the older version and then
installing CICS Transaction Gateway
Version 5.0
Versions earlier than 3 No upgrade. Uninstall the product before
continuing.
The product will not install if the level of Windows is below that supported;
see “Supported software” on page 22.
30 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
Installing the CICS Transaction Gateway
Installing the CICS Transaction Gateway
For these languages, the installation process uses the language specified in
your system locale:
v English
v French
v German
v Italian
v Japanese
v Korean
v Simplified Chinese
v Spanish
v Turkish
Attention: If you are installing the CICS Transaction Gateway onto a
workstation that already has a CICS for Windows NT server installed, be
aware that both products have some files of the same name. Ensure that the
installation of the CICS Transaction Gateway does not affect the server. This is
particularly important with respect to environment settings.
To install the CICS Transaction Gateway:
1. Log on with administrator privileges. You may have Administrator
privileges by being a member of the local Administrators group, or by
being a domain Administrator.
2. Ensure that you have applied any relevant Windows service packs. See
“Supported software” on page 22 for details.
3. Close down any other programs.
4. Insert the CD into the drive. If installing from a network drive, connect
to the drive.
5. If you are installing on a Windows 2000 Terminal Server, put the terminal
server into install mode before installing. From the Control Panel click
Add/Remove Programs → Add New Programs. Click the CD or Floppy
button. Click Next, then type d:\gateways\windows\setup, where d: is
your CD or network drive.
6. If you are not installing on a Windows 2000 Terminal Server, click Start →
Run and then type d:\setup, where d: is your CD or network drive.
7. A screen listing installation options is displayed:
v Install IBM Java v1.3
You need Java to run the full CICS Transaction Gateway product, and
the configuration tool. You do not need it to run only the Client
daemon. If you select this option, follow the onscreen prompts. When
Chapter 3. Installation 31

|
|
|
|
|
|
|
|
|
Installing the CICS Transaction Gateway
installation is complete you return to this screen. To uninstall, click
Start → Settings → Control Panel → Add/Remove Programs.
v Install IBM CTG v5.0
Select this option to install the product.
8. The installation process checks the operating system. It installs or
upgrades the Microsoft Windows Installer Service if necessary (you may
have to restart your system), and configures it to run correctly.
9. A welcome screen is displayed. Click Next to display the Software
License Agreement shown in Figure 6.
Figure 6. Software license agreement
Note: License files are stored in the \license
subdirectory, in RTF format.
10. To accept the license agreement and install CICS Transaction Gateway,
check the I accept the terms in the license agreement radio button, then
click Next.
11. The Setup Type screen shown in Figure 7 on page 33 is displayed.
32 CICS Transaction Gateway: Windows Administration

Figure 7. Setup Type screen
Installing the CICS Transaction Gateway
Select Complete or Custom as appropriate, and then click Next. Ifyou
chose a complete installation, go to step 15. If you chose a custom
installation, continue at step 12.
12. If you chose a custom installation, the Custom Setup screen shown in
Figure 8 on page 34 is displayed, with the Program Files option selected:
Chapter 3. Installation 33

Installing the CICS Transaction Gateway
Figure 8. Custom Setup screen
v Click the icon next to each component to set installation options for the
component.
v Click the Space button for details of how much space is needed to
install the components that you have chosen.
v Click Change if you wish to install to a different location.
Click Next to continue.
13. The Install Option screen (Figure 9 on page 35) is displayed:
34 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
Figure 9. Install Option screen
Installing the CICS Transaction Gateway
Yes, I want to update the path
Leave this option selected. If you clear this box you will have to
update the path manually.
Install the IBM CICS Transaction Gateway as a Windows service
If you clear this box you cannot run CICS Transaction Gateway
as a service. If you are installing on a Windows Terminal Server,
you are strongly recommended to install it as a service.
Click Next.
14. The COM Object Registration Option screen is displayed. Choose which
type of COM object you want to register. You can register CICS
Transaction Gateway COM API resources as either in process or out of
process.
In process This refers to .dll files, and is the default
type.
Out of process This refers to .exe files. Choose this for
backward compatiblity with older CICS
Transaction Gateway applications.
Chapter 3. Installation 35

|
|
|
|
|
|
|
|
|
|
|
|
|
Installing the CICS Transaction Gateway
Actions after installation
Depending on your choice, either the in process or out of process libraries
are installed; both versions are not installed. In process is the
recommended choice, as it offers better performance and better support
for multiple applications on the same machine. To change this option
after installation, you must reinstall the CICS Transaction Gateway.
Click Next.
15. (Resume here if you chose a complete installation in step 11 on page 32.)
The Ready to Install the Program screen is displayed. Click Install to
continue.
16. The installation program keeps you informed of progress. When the CICS
Transaction Gateway has been successfully installed you are asked if you
want to view the README file and run the configuration tool. (Both
options are selected.) Click Finish to end the installation.
Verify the system path
Make sure that the path to the CICS Transaction Gateway executable files
appears before any network directories in your PATH statements. If the CICS
Transaction Gateway is to run as a Windows service, its environment is
determined when the system is started and is formed from System
environment variables only. The environment used by Windows services is
established before the network drives are attached when Windows starts.
Consequently, any directory in the system PATH that involves a network
drive will not be available to Windows services.
Also, Windows discards the remainder of a PATH if it finds a non-existent
directory. You will have problems running your CICS Transaction Gateway if
network directories (or non-existent local directories) are in your system PATH
before the CICS Transaction Gateway executable files paths.
A typical symptom of this problem is the appearance of a Service Control
Manager dialog box indicating a return code of 0xc0000022 when you try to
start the CICS Transaction Gateway.
Creating Start Menu shortcuts
When you install the CICS Transaction Gateway Start Menu shortcuts are
created for some of the tasks most commonly performed (see “The CICS
Transaction Gateway icons” on page 144 for details). You can create additional
shortcuts to perform the command functions that you use most frequently. For
example, you might want to create a shortcut for:
CICSCLI /s=servername /q
to start a connection to a server used for testing applications.
36 CICS Transaction Gateway: Windows Administration

To create a Start Menu shortcut:
1. Right-click one of the existing shortcuts on the Start Menu, for example
Start Client.
2. Select Create Shortcut from the menu.
3. A new Start Menu shortcut, for example Start Client (2), appears on the
menu. Right-click the new Start Menu shortcut.
4. Select Properties from the menu.
5. Change the settings for the new Start Menu shortcut under the Shortcut
tab.
6. Change the name for the new Start Menu shortcut under the General tab.
7. Click OK to save the Start Menu shortcut properties.
Maintaining or uninstalling the CICS Transaction Gateway
Actions after installation
This section describes how to:
v Change installed components
v Repair installation errors
v Completely remove the CICS Transaction Gateway
1. To maintain CICS Transaction Gateway, run the setup file as described in
“Installing the CICS Transaction Gateway” on page 31. Follow the
instructions to step 8.
2. Click Next to clear the welcome screen.
3. The Program Maintenance screen shown in Figure 10 on page 38 is
displayed:
Chapter 3. Installation 37

Maintaining the CICS Transaction Gateway
Figure 10. Program Maintenance screen
Modify This displays the custom setup screen (see Figure 8 on
page 34), from which you can change which components
are installed.
Repair This option repairs installation errors. Select it, then follow
the prompts to repair any errors in your setup. The repair
option fixes missing or corrupt files, shortcuts, and registry
entries.
Remove This removes the CICS Transaction Gateway from your
computer.
38 CICS Transaction Gateway: Windows Administration
Note: If you selected the Use Windows credentials for
security option on the Server connection panel of
the configuration tool, see “Use Windows
credentials for security” on page 77 for important
information about what you must do before you
uninstall.

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/ts/cics/ and follow the Support link.
You install updated versions of CICS Transaction Gateway, or corrective
service software using setup.exe, in the same way as for the initial installation.
When you update with a newer version of the CICS Transaction Gateway,
Setup retains any customized (*.ini) files from the older version.
Silent installation
You can use a silent installation to install the standard components of CICS
Transaction Gateway without going through any of the Setup screens. You run
only the setup program; no user input is required.
You must first install the CICS Transaction Gateway on a workstation using
the instructions in “Installing the CICS Transaction Gateway” on page 31.
During installation, the following file is created on your workstation:
\silent.txt
This file contains instructions on how to install silently.
Updating the CICS Transaction Gateway
Chapter 3. Installation 39

40 CICS Transaction Gateway: Windows Administration

|
|
|
|
Chapter 4. Setting up communication with CICS servers
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. This
chapter consists of the following:
“TCP/IP configuration” Read this if you will use TCP/IP.
“TCP62 configuration” on page 42 Read this if you will use TCP62.
“SNA configuration” on page 45 Read this if you will use the Systems
Network Architecture. (References to SNA
mean the APPC implementation of SNA.)
“Named Pipes configuration” on page 50 Read this if you will use Named Pipes to
communicate with a TXSeries (Version 4.3
or later) for Windows NT server that is
on the same computer as your CICS
Transaction Gateway.
“Data conversion” on page 50 Read this for information on how data
may be converted as it passes between
the CICS Transaction Gateway and a
CICS server.
A number of sample configuration documents provide step-by-step guidance
on configuring the CICS Transaction Gateway and CICS servers for different
scenarios. If one of the documents covers your desired configuration, simply
follow the instructions in it. See “Sample configuration documents” on
page 266.
After you have set up your communications links, continue at Chapter 5,
“Configuration” on page 51. This tells you how to make the required entries
in the configuration file.
TCP/IP configuration
The TCP/IP stack on your local machine should already be correctly
configured. Contact your system administrator if there are problems.
Next steps
1. Use the configuration tool to create a server definition; see “The
configuration tool interface” on page 55.
2. Configure the server definition (see “TCP/IP settings” on page 78):
© Copyright IBM Corp. 1996, 2002 41

|
|
|
|
TCP/IP configuration
Specify TCP/IP as the protocol.
Enter the hostname or IP address of your CICS server.
TCP62 configuration
The TCP62 support for CICS Transaction Gateway allows communication with
CICS for MVS/ESA Version 4.1 and later over a TCP/IP network.
On CICS for MVS/ESA Version 4.1 and 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 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 43.
TCP62 links to the CICS Transaction Gateway support data synchronization
levels (sync levels) 0 and 1.
Enabling 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. For more details, see “Sample
configuration documents” on page 266, and “Redbooks” on page 267. You also
need to make entries in the configuration file; see Chapter 5, “Configuration”
on page 51.
Table 6 shows the entries that you need to make. The values in the Example
column are taken from the sample configuration documents.
Table 6. 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
hursley.ibm.com
NETID - Partner LU name. The
Partner LU name is
NETID.APPL.
ABC3XYZ4
APPL Applid Partner LU name IYCKCTU1
LOGMODE Modename Mode name LU62PS
42 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 6. Matching definitions for TCP62 on z/OS, CICS, and configuration file. (continued)
z/OS CICS configuration tool Client workstation Example
IP address mask for
LU name template
(optional)
TCP/IP subnet mask FFFFFE00
On z/OS
Fully qualified CP
name or template
Local LU name or
template
TCP62 configuration
ABC3XYZ4.PQRS1234
CCLI****
1. Define the TCP/IP address and hostname 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 book, SC31-6527.
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 have 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. 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.
Chapter 4. Setting up communication with CICS servers 43

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TCP62 configuration
On CICS Transaction Server for z/OS
On CICS:
1. Set the following SIT parameters:
ISC=YES
APPLID=IYCKCTU1
AIEXIT=DFHZATDY
where IYCKCTU1 is the VTAM APPL that you defined earlier.
2. Install these groups:
v DFHISC
v DFHCLNT
3. Define an SNA connection to the client workstation. (You can define the
connection statically, or autoinstall it.)
v On the MODENAME option of the SESSIONS definition, specify the
same modename as your VTAM LOGMODE. You will also use this
value in 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 83. The default is 8;
increase this if necessary. Specify the second value as 1, that is, that
CICS is to have one contention winner. For example, MAXIMUM(8,1)
means that the modeset is to support eight sessions, and that CICS has
one contention winner.
On the 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 Place the name and IP addresses in the hosts file
(%windir%\system32\drivers\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.
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 83.
44 CICS Transaction Gateway: Windows Administration

|
|
|
|
KeepAlive packets
When using CICS Transaction Gateway, with the TCP62 protocol, KeepAlive
packets can be sent to the CICS server to check its availability.
KeepAlive packets are enabled by default.
You can enable or disable the sending of KeepAlive packets using the Remote
node inactivity poll interval setting in the configuration tool; see “Remote node
inactivity poll interval” on page 83.
Changing this inactivity poll value alters how frequently CICS Transaction
Gateway sends KeepAlive packets. A higher interval value will result in less
network traffic but CICS Transaction Gateway will take longer to detect that a
connection has been lost. With a lower value the opposite is true, lost
connections are detected and there ish a greater amount of network traffic.
Next steps
1. Use the configuration tool to create a server definition using the TCP62
protocol; see “The configuration tool interface” on page 55.
2. Configure the server definition (see “TCP62 settings” on page 80).
SNA configuration
TCP62 configuration
To set up communication over SNA, define the following in your SNA
communications product:
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 (PLU) 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 SNA support. The terms used above are the ones used by
IBM eNetwork Communications Server.
SNA links to the CICS Transaction Gateway support data synchronization
levels (sync levels) 0 and 1.
Chapter 4. Setting up communication with CICS servers 45

Configuring SNA
Configuring SNA
The following sections summarize SNA configuration. Configuring SNA
requires action on VTAM, CICS, the CICS Transaction Gateway, and one of
the following:
v eNetwork Personal Communications
v eNetwork Communications Server
v Microsoft SNA Server
Table 7 shows the entries that you need to make. The values in the Example
column are taken from the sample configuration documents.
Table 7. Matching definitions for SNA
VTAM CICS eNetwork Personal
Communications
NETID — First part of
Partner LU name
eNetwork
Communications
Server
First part of
Partner LU name
Microsoft SNA
Server
configuration file Example
Network Name Partner LU name ABC3XYZ4
PU — CP Alias CP Alias Control Point
Name
— IYAMR004
LU Netname Local LU name Local LU name LU Name Local LU name IYAMT040
XID — Local Node ID Local Node ID Local Node ID — 05D 316DF
Token Ring — Destination Destination Remote Network
— 400045121088
destination
address
address
address
Address
APPL Applid Second part of
Partner LU name
Second part of
Partner LU name
Remote LU Name Partner LU name IYCKCTU1
LogMode Modename Mode name Mode name Mode Name Mode name LU62PS
Host
system
control
point name
— CP Name — — — —
IBM eNetwork Communications Server
Install eNetwork Communications Server client on a machine that contains the
CICS Transaction Gateway, which in turn communicates with the CICS server
through the eNetwork Communications Server machine.
For information on installing and configuring eNetwork Communications
Server, and eNetwork Communications Server clients, see the IBM eNetwork
Communications Server Up and Running Guide.
Run Configuration to configure Global Data and the LU6.2 Server List.
Setting up the eNetwork Communications Server (server): Run SNA Node
Configuration to configure SNA support, define a connection and the local
LU, partner LU and mode specified in the configuration file. Configure the
local LU to be independent.
46 CICS Transaction Gateway: Windows Administration

Configuring SNA
If using a eNetwork Communications Server SNA Client, ensure that the SNA
API client use check box, in the Local LU 6.2 definition panel, is selected.
To enable ATI against CICS Client terminals, define the transaction program
CRSR on the eNetwork Communications Server, whether or not an eNetwork
Communications Server SNA Client is being used:
TP name CRSR
Service TP No
Complete pathname C:\PROGRA~1\IBM\IBMCIC~1\BIN\CCLCLNT.EXE
Program parameters CRSR
Conversation type Mapped
Synchronization level
Conversation security required
Any
No
Receive_Allocate timeout 0
Incoming allocate timeout default
TP instance limit 1
PIP allowed No
For SNA Client use Yes/No
Dynamically loaded No
Full duplex support No
Setting up the eNetwork Communications Server Windows client: Run
Configuration to configure Global Data and the LU6.2 Server List.
To enable ATI against CICS Client terminals, define the transaction program
CRSR on the SNA Client:
TP name CRSR
LU alias Alias of the local LU defined for the
connection
Complete pathname C:\PROGRA~1\IBM\IBMCIC~1\BIN\CCLCLNT.EXE
Program operation Attach Manager Started
Program parameters CRSR
Service TP No
Attach Manager Started No
Chapter 4. Setting up communication with CICS servers 47

Configuring SNA
The Attach Manager must be started.
Configuration documentation: For step-by-step guidance on connecting
CICS Transaction Gateway to CICS Transaction Server for z/OS, using
eNetwork Communications Server, see “Sample configuration documents” on
page 266.
IBM eNetwork Personal Communications
1. Run SNA Node Configuration to configure SNA support.
2. Define a node, a device and a connection. Use an adjacent CP type of
APPN Node or Back-Level LEN in the connection definition.
3. Define the local LU, partner LU and mode specified in the configuration
file. Configure the local LU to be independent.
4. Start the node from SNA Node Operations before starting a connection
from the Client daemon to a server that uses eNetwork Personal
Communications.
5. To enable ATI against CICS client terminals, define the transaction
program CRSR:
TP name CRSR
Service TP No
Complete pathname C:\PROGRA~1\IBM\IBMCIC~1\BIN\CCLCLNT.EXE
Program parameters CRSR
Conversation type Mapped
Synchronization level Any
Conversation security required
No
Receive_Allocate timeout 0
Incoming allocate timeout default
TP instance limit 1
PIP allowed No
For SNA Client use Yes/No
Dynamically loaded No
Full duplex support No
Running eNetwork Personal Communications: Start the IBM eNetwork
Personal Communications node before you start a SNA connection from the
Client daemon. The TCP62 protocol driver automatically starts the IBM
Personal Communications node when a Client daemon TCP62 connection is
48 CICS Transaction Gateway: Windows Administration

started, if it is not already running. If the node is started automatically the
default configuration file is used, if one exists. If the node is started manually
and the TCP62 protocol is required, configure an AnyNet SNA/IP device,
specifying the SNA domain name suffix in the Anynet domain name suffix
setting in the configuration file.
Configuration documentation: For step-by-step guidance on connecting
CICS Transaction Gateway to CICS Transaction Server for z/OS, using
eNetwork Communications Server, see “Sample configuration documents” on
page 266.
Microsoft SNA Server
Install SNA Server client on a machine that contains the CICS Transaction
Gateway, which in turn communicates with the CICS server through the SNA
Server machine.
For information on installing and configuring Microsoft SNA Server, and SNA
Server clients, see the Microsoft SNA Server Installation Guide, and the Microsoft
SNA Server Administration Guide.
To allow workstations using the Windows SNA Client to communicate with
other systems, define the LUs used by the client systems as Local APPC LUs
to the SNA Server workstation.
Setting up the SNA Server Windows client: On the SNA Server Windows
client, enter the following:
SNA client mode Remote
Primary Server Name of the SNA Server workstation that the
client systems using SNA Client will use. This
computer name of the SNA Server is
displayed in both the SNA Server Admin
Servers and Connections window, and in the
Network Settings control panel dialog box.
To receive ATI on SNA Server Windows client terminals, run the CCLMSATI
command to configure the SNA Server Client for the CRSR transaction. The
syntax of the command is:
CCLMSATI luname
where luname is the LocalLU you are using.
Configuring SNA
If CRSR is already configured, the LocalLU setting changes to match the new
value.
Chapter 4. Setting up communication with CICS servers 49

Configuring SNA
Before you start the SNA Server Windows client, run SNABASE.EXE to start
the SNA Server Client SnaBase. If you do not, the CICS Transaction Gateway
cannot communicate with the SNA Server.
Configuration documentation: More information on connecting CICS
Transaction Gateway to CICS Transaction Server for z/OS, using SNA Server,
is in CICS Transaction Gateway V3.1 The WebSphere Connector for CICS. See also
“Sample configuration documents” on page 266, for step-by-step guidance on
configuration for specific scenarios.
Named Pipes configuration
CICS Transaction Gateway can use the Windows Named Pipes protocol to
communicate with TXSeries (Version 4.3 or later) for Windows NT servers that
are on the same computer. This provides a fast communications method
independent of any network protocol.
Data conversion
The following definitions are required:
v The TXSeries server must have a Listener Definition for the NamedPipe
protocol.
v The NamedPipeName attribute must match the Named pipe name setting
in the CICS Transaction Gateway configuration. All other attributes can use
their default values. Named pipe name must be 6 alphanumeric characters,
for example, CICSCC.
v The Named pipe name setting in the configuration file must match the
NamedPipeName attribute in the TXSeries server Listener Definition. Use
the configuration tool to select the Named pipe protocol, in the Server
panel (see “Configuring Server settings” on page 76). This creates the
correct settings in the configuration file including a LOCALNP Driver section
with DriverName set to CCLCLPIP.
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 may have 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/390 server system. Data conversion is performed by the
server system. For more information on this see Appendix A, “Data
conversion between the Client daemon and a CICS server” on page 251.
50 CICS Transaction Gateway: Windows Administration

Chapter 5. Configuration
This chapter describes how to configure your CICS Transaction Gateway. It
consists of the following:
“Before you start” on page 52 Read this for information on what to do
before configuring the CICS Transaction
Gateway.
“Using the configuration tool” on page 54 Read this for general information on
configuring the CICS Transaction
Gateway, including:
v How to change the default location of
your configuration details
v Using the Task Guide to define basic
details about your CICS server and the
protocols you will use
“Configuring CICS Transaction Gateway
settings” on page 58
“Configuring Client settings” on page 71
“Configuring Server settings” on page 76
“Configuring the Workload Manager” on
page 84
Read this if you want to allow non-CICS
applications written in Java to
communicate with CICS servers.
Read these sections if you want to set up
communication with CICS servers.
Read this for information on configuring
the Workload Manager. The Workload
Manager can help to improve
performance by distributing work across
CICS servers.
“Editing the configuration file” on page 89 Read this if you prefer to edit the
configuration file direct, rather than use
the configuration tool.
“Keyboard mapping for CICSTERM” on
page 97
“Customizing the screen colors for
CICSTERM” on page 99
“Preparing to use local CICS Transaction
Gateway support” on page 101
Read these sections if you intend to use
CICSTERM.
Read this for information on setting up
your Java environment correctly.
A number of sample configuration documents provide step-by-step guidance
on configuring the CICS Transaction Gateway and CICS servers for different
scenarios. If one of the documents covers your desired configuration, simply
follow the instructions in it. See “Sample configuration documents” on
page 266.
© Copyright IBM Corp. 1996, 2002 51

Configuration
Before you start
See also:
v IBM Redbooks (see “Redbooks” on page 267)
v Chapter 4, “Setting up communication with CICS servers” on page 41
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 41.
Note: You must restart the Client daemon and the Gateway daemon for any
changes to the configuration file to take effect.
Gather information
Have the following information available:
v The protocol you will use to connect to the CICS server (TCP/IP, TCP62,
SNA, or Named Pipe)
v The hostname or IP address of the server
v The port number at the server to which the Client daemon should connect
v The protocols you will use with the Gateway (TCP, SSL, HTTP and HTTPS)
See Table 6 on page 42, and Table 7 on page 46, for information on matching
definitions for TCP62 and SNA.
Log on with administrator privileges
Before you configure the CICS Transaction Gateway, you must be logged onto
the machine with Administrator privileges. You may have Administrator
privileges by being a member of the local Administrators group, or by being a
domain administrator.
See “Running CICS Transaction Gateway as a Windows service” on page 146
for more information.
Set the JVM
Under Windows, it is acceptable to have more than one Java Virtual Machine
(JVM) installed on a machine. If so, applications need to know which one to
use. The ctgjava command allows you to view or alter the JVM used by the
CICS Transaction Gateway.
Seeing which JVM is in use
Issue this command to find out which JVM the CICS Transaction Gateway is
set to use:
ctgjava -v
52 CICS Transaction Gateway: Windows Administration

Setting the JVM
Issue this command to set the JVM that the CICS Transaction Gateway uses:
ctgjava -s=jvmlocation
where jvmlocation is the fully qualified pathname of the Java executable file.
If the pathname contains spaces, enclose it in quotation marks. For example:
ctgjava -s="C:\Program Files\IBM\Java13\bin\java.exe"
Selecting a JVM automatically
Issue this command to auto-configure the JVM for the CICS Transaction
Gateway:
ctgjava -a
Set the time
You must set your locale to match your timezone to get the right time. For
example, if you set your locale to en_US, Java is set to the time in the United
States.
Configure your programming environment
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)
v cfwk.zip (if you are using SSLight security)
These archives are in the \classes subdirectory.
Set the CLASSPATH
Use a command like the following to set the CLASSPATH environment variable:
set CLASSPATH=c:\ibmvaj\classes;\classes\ctgclient.jar;%CLASSPATH%
Configuration
This command makes the classes in directory c:\ibmvaj\classes, and in
archive \ctgclient.jar, accessible by the JVM.
You can also set and change the CLASSPATH environment variable from the
Environment tab dialog in the System dialog in the Control Panel.
Chapter 5. Configuration 53

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Configuration
Use the following command to display the value of the CLASSPATH
environment variable:
set CLASSPATH
Using the configuration tool
Use the configuration tool to configure the CICS Transaction Gateway.
To start the configuration tool, click the icon, or enter the ctgcfg command.
The configuration tool uses the JVM specified by the ctgjava command; see
“Set the JVM” on page 52.
Task Guide
The first time you run the configuration tool, you are asked if you want to
use the Task Guide to define basic information about your system. The
Task Guide allows you to enter details of your CICS servers, and enable
the TCP and HTTP protocols for the Java gateway. You can change any of
the settings you enter here later, through the configuration tool. You can
bypass the Task Guide, and go straight to the configuration tool, by
clicking No when asked if you want to use the Task Guide. You are
recommended to use the Task Guide unless you use a screenreader; see
“Accessibility” on page 271.
For help in completing any of the screens on the Task Guide, refer to the
online help, or the relevant section in “The configuration tool interface” on
page 55.
The configuration file
Configuration details are stored by default in the CTG.INI file in the
\bin subdirectory. IBM recommends that you use the
configuration tool to update this file.
You can specify a different path to the configuration file by setting the
CICSCLI environment variable. (The CICS Transaction Gateway log
indicates the location of CTG.INI.) The CICS Transaction Gateway will not
run if a configuration file is not found.
The Task Guide also launches if it fails to find CTG.INI in the
\bin subdirectory. If you specified a different location for
the configuration file through the CICSCLI environment variable, and
wish to edit an existing configuration file, click No when asked if you
want to use the Task Guide. Once the configuration tool has launched,
open your configuration file.
Running the configuration tool on a different operating system
You can use the configuration tool on any of the other CICS Transaction
Gateway operating systems to generate a configuration file for your operating
system. See Appendix B, “Hardware and software” on page 257 for other
supported operating systems.
54 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
1. Install 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:
ctgcfg -PLAT WIN
This makes the configuration tool run as if it is on your operating system.
4. Make the required entries and click Save. This creates or updates the
CTG.INI file.
5. Use FTP in ASCII mode to transfer the file to your system.
The configuration tool interface
The screen has four input areas (described separately below):
1. Menu bar
2. Toolbar
3. Tree structure
4. Settings panel
Configuration
A fifth area, the status bar, shows which configuration file and operating
system you are using. The status bar is display only.
Chapter 5. Configuration 55

Configuration
Figure 11. The configuration tool
Tree structure
The tree structure (see Figure 11) allows you to navigate through all of the
settings in your configuration. The types of root node are as follows:
Java Gateway Contains a subnode for each protocol that the CICS
Transaction Gateway can use (TCP, SSL, HTTP, HTTPS and
TCPAdmin).
Client Contains a subnode for each of your server definitions.
Workload Manager
Contains two subnodes:
Server Groups
56 CICS Transaction Gateway: Windows Administration
Server groups are used to group together
CICS server definitions with different port
numbers. These server instances are used by
the Workload Manager to balance workload
across CICS servers. Each server group
subnode contains the server definitions
associated with that server group.

|
|
|
|
|
|
|
|
Configuration
Programs Contains a number of subnodes, one for each
program associated with the Workload
Manager. Each program subnode contains the
server definitions with which the program is
associated.
Menu bar
The menu bar contains the File, Edit, Tools, Settings, and Help pulldowns.
The File pulldown has the following options:
New Creates a new configuration.
Open Opens an existing configuration.
Save Saves the current configuration. If a new configuration has
been created, the file name is CTG.INI (in 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 pulldown has Cut, Copy and Paste options, which perform the
standard text functions.
The Tools pulldown has the following options:
Trace Settings Displays the Trace Settings dialog.
Task Guide Starts the Task Guide for creating new server definitions.
New Server Defines a new server named A_Server, that uses the TCP
protocol. Recommended for users of screenreaders and expert
users; otherwise use the Task Guide option.
Delete Server Deletes a server node from the tree structure.
New Server Group
Creates a new Server group for the Workload Manager.
Delete Server Group
Deletes a Server group subnode from the Workload Manager
node.
New Program Definition
Allows you define a new program for biasing by the
Workload Manager.
Delete Program Definition
Deletes a program subnode from the tree structure.
Chapter 5. Configuration 57

|
|
|
|
|
|
|
|
|
|
|
Configuration
The Settings pulldown 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.
Any changes that you make to color and font settings are lost when you close
the configuration tool.
The Help pulldown has the following options:
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” on page 271.
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 tree structure, 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 CICS Transaction Gateway settings
To display the Gateway 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.
58 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
If a parameter defined using the configuration tool is specified via the
associated command line option when the Gateway is started, the command
line setting takes precedence.
General Gateway settings
See Figure 11 on page 56 for the screen layout. The general Gateway settings
are:
Initial number of Connection Manager threads: Enter the initial number of
ConnectionManager threads. The default is 1.
Set this to the normal number of JavaGateway objects opened by all
connected Java clients.
You can override this setting with the ctgstart -initconnect command.
Maximum number of Connection Manager threads: Enter the maximum
number of ConnectionManager threads. The default is 100.
This limits the maximum number of JavaGateway objects opened by all
connected Java clients. Set this to the maximum number of JavaGateway
objects that could be open at any one time from all the remotely-connected
Java clients.
You can override this setting with the ctgstart -maxconnect command.
If you select the Unrestricted checkbox, no limits are applied to the number of
ConnectionManager threads.
For information on threading limits, see Table 3 on page 17.
Configuration
Initial number of Worker threads: Enter the initial number of Worker
threads. The default is 1.
Set this to the normal number of concurrent requests expected to be processed
concurrently by the CICS Transaction Gateway daemon.
You can override this setting with the ctgstart -initworker command.
Maximum number of Worker threads: Enter the maximum number of
Worker threads. The default is 100.
This limits the maximum number of parallel ECI, ESI and EPI requests that
the CICS Transaction Gateway can process. Set it to:
v Less than or equal to maxconnect (for single JavaGateway programs)
Chapter 5. Configuration 59

|
|
|
|
|
|
|
|
|
Configuration
If you select the Unrestricted checkbox, no limits are applied to the number of
Worker threads.
You can override this setting with the ctgstart -maxworker command.
For information on threading limits, see Table 3 on page 17.
Enable reading input from console: Select this check box to enable the
reading of input from the console.
Reading of input from the console is enabled by default.
You can override this setting with the ctgstart -noinput command.
Display TCP/IP hostnames: Select this check box to enable the display of
TCP/IP hostnames 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 hostnames in messages. This makes the
messages easier to read.
Note: Selecting this option might cause severe performance reduction on
some systems.
Let Java clients obtain generic ECI replies: Select this check box if you wish
Java clients 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.
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.
60 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 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 The same message qualifier can be used on an asynchronous call even if a
reply with that 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.
Log 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
client application program connects to, or disconnects from, the Gateway
daemon. The default is for these messages not to be written.
Timeout for in-progress requests to complete (ms): Enter a value in
milliseconds.
When a Java-client program disconnects from the Gateway, the Gateway may
still be processing requests on behalf of that program. If work is still in
progress, the ConnectionManager that was managing requests on behalf of
that Java-client waits for the requests to complete for up to the timeout
period. If there are still requests in progress after the timeout has expired, the
ConnectionManager continues its processing and marks itself as available for
use by a new connection. The default timeout is 10 000 milliseconds, but you
may enter a value to override the default.
If this value is set to zero, the ConnectionManager does not wait for
in-progress requests to complete.
Worker thread available timeout (ms): Enter a value in milliseconds.
Configuration
When a ConnectionManager accepts a request, it must allocate a Worker
thread to execute that request. If a Worker does not become available within
Chapter 5. Configuration 61

Configuration
Figure 12. TCP settings
the 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 is
immediately available.
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.
Port: Enter the TCP/IP port number.
62 CICS Transaction Gateway: Windows Administration

The default port for TCP/IP is 2006.
You can override this setting with the ctgstart -port command.
Handler wakeup timeout (ms): Enter a value in milliseconds.
This setting controls how frequently the protocol handler wakes from
accepting inbound connections. When it wakes, it checks to see whether the
Gateway is being stopped, and so this value affects the time taken for the
Gateway to shutdown cleanly. If you set this value to zero then the handler
only wakes when a new connection is accepted, and so the Gateway will not
shutdown cleanly until that time.
Connection timeout (ms): Enter a value in milliseconds.
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,
then the connection is refused. If this value is set to zero, a connection is
refused if a ConnectionManager is not immediately available.
Idle timeout (ms): Enter a value in milliseconds.
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 connection is
disconnected, though if work is still in progress on behalf of the connection, it
may be left connected. If this value is not set, or is set to zero, then idle
connections will not be disconnected.
Cleanup processing will only result after a timeout if the server has support
for this function installed.
Ping time frequency (ms): Enter a value in milliseconds.
Configuration
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 PONG response has not
been received by the time the next PING message is due to be sent, then the
connection is disconnected. Again, if work is still in progress on behalf of the
connection it may (depending on the drop working connections value setting)
be left connected. If this value is not set, or is set to zero, then PING messages
are not sent.
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.
Chapter 5. Configuration 63

Configuration
SO_LINGER setting: Enter a SO_LINGER setting for any socket used by this
handler. The SO_LINGER setting specifies a delay value in seconds for closing
a socket. If this value is not entered, or set to zero, then SO_LINGER is
disabled for any sockets used by this protocol handler.
If SO_LINGER is enabled, and data transmission has not finished, a Close call
blocks the calling program until the data is transmitted or until the connection
times out. If SO_LINGER is disabled, a Close call 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.
Require clients to use security classes: Select this check box if you wish
your Gateway to accept only connections that use security classes.
When a Java-client program 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 12.
64 CICS Transaction Gateway: Windows Administration

Figure 13. SSL settings
SSL protocol settings
Configuration
Select the SSL subnode to display the settings for SSL. 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 either the
ssl: or https: 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
“Configuring your SSL clients” on page 108.
Chapter 5. Configuration 65

Configuration
KeyRing or Keystore name: Enter the server KeyRing classname for SSLight,
or the server KeyStore name for JSSE.
For a KeyRing, do not include the .class file extension in the classname.
For a KeyStore, 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:
c:/mykeys/jsse/keystore.jks
c:\\mykeys\\jsse\\keystore.jks
The server KeyRing or KeyStore consists of a valid x.509 certificate that
identifies this server to connecting clients. This KeyRing or KeyStore is
generated using the SSL tools supplied with this product.
For more information about SSL and its associated KeyRings or KeyStores, see
Chapter 6, “Network Security” on page 103.
KeyRing or Keystore password: Enter the password that you specified for
the server KeyRing or KeyStore.
CICS Transaction Gateway writes the password to the configuration file in a
form that prevents a casual observer from easily reading it.
66 CICS Transaction Gateway: Windows Administration

Figure 14. HTTP settings
HTTP protocol settings
Select the HTTP subnode to display the settings for HTTP. The settings are
the same as for TCP.
The default port for HTTP is 8080.
Configuration
Chapter 5. Configuration 67

Configuration
Figure 15. HTTPS settings
HTTPS protocol settings
Select the HTTPS subnode to display the settings for HTTPS. The settings are
the same as for HTTP except that HTTPS also has Use client authentication,
KeyRing or Keystore name, and KeyRing or Keystore password settings. See
“SSL protocol settings” on page 65 for details.
The default port for HTTPS is 443. However, on some operating systems,
processes require special privileges to access port numbers between 1 and
1024. If you plan to run CICS Transaction Gateway without these required
privileges, change the port number to a value greater than 1024.
68 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
Figure 16. TCPAdmin settings
TCPAdmin protocol settings
Configuration
Select the TCPAdmin subnode to display the settings for administration. The
settings are the same as for TCP except for the following:
v The default port is 2810
v There is no Require clients to use security classes field.
v TCPAdmin also has the following settings:
Max dedicated connections: Enter a value specifying the maximum number
of simultaneous dedicated client connections that can be made to the Gateway
administration handler.
Authorized Hosts: Enter a host name or IP address in the entry field. Click
Add to add the host to the Authorized Hosts list, below the entry field. Click
Remove to remove all selected hosts from the Authorized Hosts list.
Chapter 5. Configuration 69

|
|
|
|
|
|
|
|
|
Configuration
If there are entries in the Authorized Hosts list, only those hosts are allowed
to access the administration protocol handler. Be aware: If the list is empty, all
hosts are allowed access.
The default entry is 127.0.0.1, which represents the host on which the CICS
Transaction Gateway is installed. IP address 127.0.0.1 and the host name
localhost are considered to be different from the real IP address or host name
of the system.
For information about administering your system, see “Administering your
system” on page 149.
70 CICS Transaction Gateway: Windows Administration

Configuring Client settings
Figure 17. Client settings
Select the Client node to display the Client Settings panel. The settings map
to the parameters in the Client section of the CTG.INI file.
Default Server
Select the default server from the drop-down list.
Applid
Enter up to 8 characters, or leave this field with the default value of *.
Configuration
This value specifies the applid of the CICS Universal Client 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.
Chapter 5. Configuration 71

Configuration
Note: If the client is to be autoinstalled to more than one CICS server, and if
you enter a specific name for the applid, that name must be unique
with respect to all servers it is connected to. If the name is not unique,
then attempts to connect to a server may be rejected because another
client has already been installed using the same name. If a name of * is
used, the client may be known by a different unique name at each
server.
If the client is to communicate with a given server via SNA, this applid may
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.
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 value does not include an overhead of 512 bytes needed by the
clients for some protocols.
Leave this setting at the default unless the CICS Transaction Gateway is
running on a machine that is short of memory.
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.
Maximum servers
Enter a value in the range 1 through 256. The default is 10.
This value specifies the maximum number of servers that can be accessed
concurrently from the client.
Maximum requests
Enter a value in the range 1 through 10 000. The default is 256.
This value specifies the maximum number of concurrent items that may be
executing on the Client daemon, where an item is one of:
v a terminal emulator
72 CICS Transaction Gateway: Windows Administration

v an EPI 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 may be
less than this setting if other operating system limits (for example, memory
constraint or communication sessions), come into effect.
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.
A command file may be necessary to act as an interface between the syntax of
the invocation command defined here, and more general operating system
syntax. For example, if the desired final command was COPY printfile LPT2, a
simple command file would be required to reorder the parameters. It is the
responsibility of the Print Command to delete the temporary print file after it
has finished processing it.
You may specify only a local executable in this field. UNC paths of the type
\\User1\Share\Notepad.exe do not work, due to the system limitations of
running executables that are installed on one machine on a different machine.
See also the Print file description for more information.
Print file
Enter a character string, 1 to 256 characters long.
Configuration
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.
If both this setting and Print command are omitted, the default action is to
direct the print data to LPT1.
Chapter 5. Configuration 73

Configuration
Note: This setting acts only as a default. The terminal and print emulators
provide options to override this value.
Codepage identifier override
Enter a value indicating a Coded Character Set Identifier (CCSID) to override
your local codepage 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 codepage 850 includes Euro support.
For codepage 1252, specify a CCSID value of 5348.
Notes:
1. Regardless of the value in the Codepage identifier override setting,
cicsterm always displays characters based on the local codepage of the
workstation.
2. If you use the CCSID to change the codepage identifier, data that is
already stored on the server may be modified when retrieved by the CICS
Transaction Gateway, if it includes characters for which the code points
produce different characters.
3. You do not have to supply a CCSID, as you can use the Use OEM
codepage setting to provide support for Euro enabled codepages. Any
value that you enter in the Codepage identifier override field overrides
the codepage value generated using the Use OEM codepage setting. You
might do this, for example, to switch back to codepage 850 or 1252 to
indicate to the CICS server that the Euro should not be used.
For more information on CCSIDs and data conversion, refer to Appendix A,
“Data conversion between the Client daemon and a CICS server” on page 251.
Server retry interval
Enter a number of seconds. This is 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.
Log file
Enter the name of the log file to be used for problem diagnosis.
If not specified, the log filename defaults to CICSCLI.LOG in the
\bin subdirectory.
74 CICS Transaction Gateway: Windows Administration

IBM recommends that you specify a ctglog subdirectory in a directory to
which all users have write access. For example, on Windows NT systems:
C:\Winnt\Profiles\All Users\Application Data\ctglog
or, Windows 2000 and Windows XP systems:
C:\Documents and Settings\All Users\Application Data\ctglog
Configuration
All users can read the log file. In a Windows secured environment, if the CICS
Transaction Gateway is running as a service, you may want to alter the
permissions of this directory to prevent users writing to the log files.
Enable popups
Select this check box to enable the display of popup messages at startup.
You can also change this setting dynamically by using the E and N options
with the CICSCLI command; see “The CICSCLI command” on page 156.
Use OEM codepage
Select this check box if you want the CICS Transaction Gateway to call the
Windows operating system OEM codepage function to get the codepage
identifier (for example, 850). If the workstation is Euro enabled, then codepage
850 is mapped to 858 within the client to indicate to the CICS Server that the
Euro symbol can be used.
If you do not select this check box, the CICS Transaction Gateway uses the
Windows operating system ACP function to get the ASCII identifier (for
example 1252). Use this to provide appropriate conversions for Latin-1,
Japanese, Korean and Simplified Chinese systems. If the workstation is Euro
enabled, codepage 1252 is mapped to codepage 5348.
For more information on codepages and data conversion, refer to Appendix A,
“Data conversion between the Client daemon and a CICS server” on page 251.
Chapter 5. Configuration 75

Configuration
Configuring Server settings
Figure 18. Server settings
Select a server in the tree structure to display the Server Settings panel. The
settings map to the parameters in a Server section of the CTG.INI file.
Server name
Enter a name of between 1 and 8 characters. This provides a
communications-protocol-independent name for the server, local to the Client
daemon.
Requests to access the server from ECI, EPI, ESI, or terminal emulators
reference the server through this name.
Description
Enter a description for the server of between 1 and 60 characters. This
description is optional.
76 CICS Transaction Gateway: Windows Administration

The description is returned to applications running on the Client daemon by
the CICS_EpiListSystems and CICS_EciListSystems functions.
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 up to the first blank in the string are taken as the
transaction. The remaining data is passed to the transaction on its invocation.
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.
Use Windows credentials for security
Select this check box if you want to use the Windows NT password for CICS
security.
To use this feature, do the following from a command prompt:
1. Change to directory
\Program Files\Common Files\IBM\IBM Integrated Sign On
2. Enter bthdinst -i CICSCLI
3. Reboot.
When uninstalling you must uninstall in the following sequence:
1. Change to directory
\Program Files\Common Files\IBM\IBM Integrated Sign On
2. Enter bthdinst -u CICSCLI
3. Reboot
4. Uninstall in the usual way.
For more information, refer to “Network Provider Interface (NPI)” on
page 126.
Configuration
Chapter 5. Configuration 77

Configuration
Use upper case security
Select this check box to specify that CICS Transaction Gateway converts to
uppercase any userid or password from an ECI application or from a user
prompt.
With this setting selected, you can enter userids and passwords in either
uppercase or lowercase. This setting is disabled by default.
Network protocol
Select from the drop-down list the protocol to be used for the server
connection:
v TCP/IP
v SNA
v TCP62
v Named Pipe
Protocol settings displayed on the panel change according to the protocol you
select.
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 (hostname) or 192.113.36.200 (IP Address).
Hostnames are mapped to IP addresses either by the name server or in the
hosts system file. It is better to use a hostname in case the IP address
changes.
The hosts system file is in the %windir%\system32\drivers\etc directory.
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.
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 %windir%\system32\drivers\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.
78 CICS Transaction Gateway: Windows Administration

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.
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.
Send TCP/IP Keepalive packets: Select this check box if you want TCP/IP
to periodically send KeepAlive packets to the server to check the connection.
SNA settings
Use LU alias names: Select this check box to use LU alias names.
Selecting this setting enables you to specify the Partner LU name and Local
LU name as aliases instead of real LU names.
An alias is a short name that you can use instead of the full partner LU name.
The SNA server maps these aliases to full partner LU names. This means, for
example, that you can switch between servers, without stopping the Client
daemon, by changing the name that an alias resolves to in the SNA server.
The default is that LU alias names are not used.
Partner LU name: Enter the LU Name of the server as it is known to the
APPC configuration at the Client daemon.
This must be an eight-character alias name.
This can be a qualified 17-character name, for example, ABC3XYZ4.PQRS1234.
Alternatively, you can enter an alias name, as long as Use LU alias names is
selected.
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.
This must be an eight-character alias name.
Configuration
You can enter an alias name, provided that Use LU alias names is selected.
Mode name: Enter between 1 and 8 characters specifying the mode name to
be used when connecting to the server.
Chapter 5. Configuration 79

|
|
|
|
|
|
|
|
Configuration
Enter * if you want the mode name to be filled with spaces.
TCP62 settings
hosts file: When configuring a TCP62 CICS server, you must also update the
local hosts file. The path to the file is:
%windir%\system32\drivers\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.
Multiple server definitions with identical combinations of Local LU, Partner
LU, and Mode name are not permitted in CTG.INI in the CICS Transaction
Gateway Version 5.0. 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. Existing Client applications that use different server
names to send requests to the same CICS region continue to work if a user
exit is defined to redirect requests. A sample user exit that does this is
provided; see \samples\samples.txt.
Partner LU name: Enter the LU Name of the server as it is known to the
SNA configuration at the client. This must be a qualified 17-character name,
for example, ABC3XYZ4.PQRS1234.
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.
80 CICS Transaction Gateway: Windows Administration

If you enter a template, you must fill in the IP address mask for LU name
template (optional) field.
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.
To use a template you must configure your CICS server to install connections
dynamically.
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.
If several hundred clients are to use dynamic LU name generation to connect
to the CICS server, you should have more template replacement characters in
your Local LU name, for example, CTS8****. In fact, CICS Transaction Server
for z/OS uses the last four characters of the LU name as the connection name,
so these characters must be unique.
IP address mask for LU name template (optional): Enter an IP address mask
in big-endian, that is, most significant byte first order. This must be a
hexadecimal number, for example, FFFFFF80.
This address mask is used in dynamic LU name generation. 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.
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.
Configuration
Use the Maximum logical SNA sessions, Maximum SNA RU size, and SNA
pacing size settings to define the mode values specified for the Mode name
on your CICS server.
Chapter 5. Configuration 81

Configuration
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.
IP address mask for CP name (optional): Enter an IP address mask in
big-endian, that is, most significant byte first order. 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.
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 hostname
LUA.NETID.sna.ibm.com to obtain the IP address of the node that has the LU
name NETID.LUA.
82 CICS Transaction Gateway: Windows Administration

See “TCP62 settings” on page 80, for information on how IP addresses map to
host names.
TCP62 port: Enter a number between 0 and 65535 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.
You must configure your CICS server with the same port number.
Remote node inactivity poll interval: Enter a number of seconds between 0
and 65535. The default value is 60 seconds. A value of 0 turns off polling.
This configuration setting controls the time that the Client daemon waits
before polling inactive connections.
The Client daemon polls inactive connections by sending MPTN keepalive
datagrams by User Datagram Protocol (UDP) to the CICS server. 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.
Advanced TCP62 settings
Maximum logical SNA sessions: Enter a value in the range 1 through 255.
The default value is 8.
This parameter defines the maximum number of logical SNA sessions
allowed. The number of concurrent transactions that can exist for a client is
restricted by the number of client contention winners available on the session.
For example, if the maximum number of sessions is 8, and the server has 1
contention winner, the client is left with 7 contention winners. This allows 7
concurrent transactions.
Maximum SNA RU size: Enter a value in the range 256 through 4096. You
are recommended to use the default value of 1024.
This parameter specifies the maximum size of the request or response units
sent over sessions.
SNA pacing size: Enter a value in the range 0 through 63. You are
recommended to use the default value of 8.
Configuration
This parameter specifies how many request units can be sent before receiving
a pacing response.
Chapter 5. Configuration 83

|
|
|
Configuration
Named pipe settings
Named pipe name: Enter a name of up to six alphanumeric characters that
match the NamedPipeName attribute specified by the TXSeries for Windows
NT server in its Listener Definition.
Configuring the Workload Manager
To display the Workload Manager Settings panel, select the Workload
Manager node in the tree structure. Most settings map to the parameters in
the LOADMANAGER section of the CTG.INI file, although the Workload
Manager also uses the REGION parameter in the SERVER section.
It is recommended that you read Chapter 12, “Workload Manager” on
page 179, before configuring the Workload Manager. That chapter explains
important concepts, such as server groups, and the behaviour of the workload
balancing algorithms.
Enable the Workload Manager
Select this check box to enable the Workload Manager. The default is that the
Workload Manager is disabled.
Round robin
Select this radio button to select a round-robin algorithm for this server.
84 CICS Transaction Gateway: Windows Administration

Biasing
Select this radio button to select a biased algorithm for the Workload
Manager.
Configuration
Region timeout (s)
Enter a value in seconds between 0 and 3600. The default is 60 seconds.
When a CICS server (region) is selected as the target of a client request, and
that server is unavailable, the server is flagged as invalid, and is no longer
included in the list of target regions for requests. The Region timeout (s) value
specifies the number of seconds after which an invalid region can once more
be included in the list of target regions.
Two options on the Tools menu allow you to configure server groups and
programs. These options are only enabled when you select the Workload
Manager node.
Configuring a server group
This panel allows you to define which servers belong to a particular server
group.
To add a new server group, you select the New Server Group option, or click
the New Server Group icon, and enter a name in the Server group name
field.
To change the members of a server group, select the server group from the
tree selection.
To add a server to a group, select from the Servers not in server group list on
the right and then select the arrow button ().
Configuring programs
This panel allows you to define the workload management for a particular
program. If the round-robin algorithm is selected, you define which servers
are valid for the program. If the biasing algorithm is selected, you define
which servers are used for biasing.
Workload management for particular programs is available only for ECI, and
not for EPI or CICSTERM.
To add a new definition, you select the New Program Definition option, or
click the New Program Definition icon, and enter a name in the Program
name field.
Chapter 5. Configuration 85

Configuration
To change a definition, select the program from the tree selection.
To disable workload management for the program, deselect the Manage
workload for this program check box.
If the round-robin algorithm is selected: To add a server to the list of
servers for which the program is valid, select from the Servers not valid for
this program list on the right and then select the arrow button ().
If the biasing algorithm is selected: To add a server to the list of servers
used for biasing, select from the Servers not used for biasing list on the right
and then select the arrow button ().
In the Bias value fields, you can enter a bias value for the server.
In the Ratios fields, percentage bias values for each server are shown. This
field contains Standby if the bias value is 0, which means use only if no other
server is available.
Manage workload for this program
Select this check box if you want to enable load balancing for the selected
program.
If you disable load balancing for a particular program, the Workload Manager
connects to the server specified in the ECI call, rather than randomly selecting
a new server.
Trace settings
To configure the trace settings, select the Trace Settings option from the Tools
menu.
Trace Settings
Select check boxes to specify the CICS Transaction Gateway and Client
daemon components that will be traced when tracing is turned on.
Trace everything
All components.
Client API level 1
The client API layer (level 1).
86 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
Gateway
The CICS Transaction Gateway.
JNI Trace
You cannot enable JNI trace through the configuration tool. Use one of
the following methods to enable it:
v When you start the CICS Transaction Gateway, issue the command
ctgstart -j-Dgateway.T.setJNITFile=filename
Configuration
where filename is the name of the file to which trace output is to be
sent.
v While the CICS Transaction Gateway is running, use the system
administration functions. You must have enabled the TCPAdmin
protocol handler (see “TCPAdmin protocol settings” on page 69). See
“Administering your system” on page 149 for details of how to enable
JNI trace dynamically.
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
Using the CTG_JNI_TRACE environment variable to enable JNI trace is
supported only for migration purposes.
Chapter 5. Configuration 87

Configuration
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.
Workload manager
The Workload Manager.
You can also use the M option with 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 156.
If you turn on tracing without specifying the components in either the cicscli
command or in CTG.INI, a default set of components is traced:
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.
Gateway trace file
Enter the pathname of a trace file to which trace messages will be written, if
tracing is enabled. If no path is specified, the trace is written as follows:
\bin\ctg.trc
IBM recommends that you place the trace file in a ctgtrace subdirectory of a
directory to which all users have write access. For example, on Windows NT
systems:
C:\Winnt\Profiles\All Users\Application Data\ctgtrace
or on Windows 2000 and Windows XP systems:
C:\Documents and Settings\All Users\Application Data\ctgtrace
Restrict read access to privileged groups, such as Administrators.
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.
88 CICS Transaction Gateway: Windows Administration

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.
Gateway trace wrap size
Enter a value in the range 0 through 1 000 000 kilobytes.
This value specifies the size in kilobytes to which the gateway trace file will
grow. Subsequent trace entries will continue to be written from the beginning
of the file. The default value of 0 disables wrapping.
Client trace file
Enter the pathname of a trace file to which trace messages will be written, if
tracing is enabled.
You do not have to enter an extension for the filename, as 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:
\bin\CICSCLI.BIN
To minimise 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 209.
Maximum Client wrap size
Enter a value in the range 0 through 65 535 KB.
This value specifies how large the trace file will grow on disk before
wrapping. The default value of 0 disables wrapping.
Editing the configuration file
Although it is recommended that you use the configuration tool you can edit
the configuration file direct.
The configuration file has the following sections:
1. GATEWAY
2. CLIENT
3. SERVER
4. DRIVER
5. LOADMANAGER
Configuration
Chapter 5. Configuration 89

|
|
|
|
|
|
|
|
Configuration
For information on the properties in each section, refer to the descriptions of
the corresponding settings in the configuration tool.
The DRIVER section has no corresponding section in the configuration tool.
The configuration tool automatically selects the correct protocol drivers.
Each section has the format:
SECTION sectioname [=value]
# Comment describing the section
property1=value
property2=value
...
propertyN=value
ENDSECTION
Note: If you use the # 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.
J2EE setup and configuration
This topic discusses the administration of CICS resource adapters. Two
resource adapters are supplied with the CICS Transaction Gateway. The
\deployable directory contains an adapter for ECI (cicseci.rar),
and one for EPI (cicsepi.rar).
Any value set by the setExecuteTimeout method of the ECIInteractionSpec
class is ignored; neither connector supports timeout. An alternative is to set
the TIMEOUT parameter in the external CICS interface options table,
DFHXCOPT. See the CICS External Interfaces Guide for more information.
Deploying CICS resource adapters
Before you can use a J2EE resource adapter in a server runtime environment
you must supply parameters for its internal ManagedConnectionFactory class.
In a managed environment you set these parameters when you deploy the
resource adapter to your server. For instructions on how to do this consult
your server’s documentation.
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.
90 CICS Transaction Gateway: Windows Administration

Deployment parameters for the ECI resource adapter
Deployment parameters for the ECI resource adapter
This section describes the available deployment parameters for the ECI
resource adapter, and their effect on the final deployed resource adapter. The
tools used to configure these parameters are server-specific. Not all
parameters are required; the default value is shown where appropriate.
ConnectionURL
The URL of the CICS Transaction Gateway with which the resource
adapter will communicate. The URL takes the form
protocol://address. These protocols are available:
v tcp
v http
v ssl
v local
So, for example, you might specify a URL of tcp://ctg.business.com.
For the local protocol simply specify local:.
PortNumber
The port to connect to where the CICS Transaction Gateway is
running. 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. This is the name as defined in the CICS
Transaction Gateway configuration file. To use multiple servers within
an environment you must deploy several resource adapters, each with
a different ServerName attribute set.
TranName
The name of the CICS Transaction under which you want all
programs started by the resource adapter to run.
TPNName
The name of the CICS TPN Transaction under which you want all
programs started by the resource adapter to run. Note that TPNName
takes precedence if both TranName and TPNName are specified.
UserName
The CICS userid to be used if no other security credentials are
available. See the J2EE section in the CICS Transaction Gateway:
Programming Guide for more information.
Password
The password for the CICS userid 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
Chapter 5. Configuration 91

Deployment parameters for the ECI resource adapter
then 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
then 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 keyring class to use. This only
applies when using the SSL protocol.
KeyRingPassword
The password for the class 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 95.
As well as these user-definable properties, the ECI 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 ECI resource adapter is defined as LocalTransaction. If your
server supports LastResourceOptimization, the resource adapter can
participate in a global transaction, provided it is the only
LocalTransaction resource that has been enlisted.
Re-Authentication Support
The ECI 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.
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. Not all of these
parameters are required; the default value is shown where appropriate.
ConnectionURL
The URL of the CICS Transaction Gateway with which the resource
92 CICS Transaction Gateway: Windows Administration

Deployment parameters for the EPI resource adapter
adapter will communicate. The URL takes the form
protocol://address. These protocols are available:
v tcp
v http
v ssl
v local
So, for example, you might specify a URL of tcp://ctg.business.com.
For the local protocol simply specify local:.
PortNumber
The port to connect to where the CICS Transaction Gateway is
running. 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. This is the name as defined in the CICS
Transaction Gateway configuration file. To use multiple servers within
an environment you must deploy several resource adapters, each with
a different ServerName attribute set.
UserName
The CICS userid 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 signon capable, or
v The CICS Server does not support signon capable terminals (for
example, CICS for OS/2)
Password
The password for the CICS userid 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
then 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
then no ServerSecurity class is used. For more information on what
ServerSecurity classes are used for, and how to write them, see CICS
Chapter 5. Configuration 93

Deployment parameters for the EPI resource adapter
Transaction Gateway security classes in the Java chapter of the CICS
Transaction Gateway Programming Guide.
KeyRingClass
The fully qualified name of the SSL keyring class to use. This only
applies when using the SSL protocol.
KeyRingPassword
The password for the class 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 terminals
on CICS that are used by the resource adapter are signon capable or
incapable. Acceptable values are:
v 0 — Signon capable terminal (default)
v 1 — Signon incapable terminal
Encoding
The Java Encoding to use when creating 3270 datastreams. The
encoding will be converted to the appropriate CCSid. See the
appendix in the CICS Transaction Gateway: Programming Reference
manual for a list of supported encodings. Ensure that your CICS
Server supports the CCSid from the given encoding.
LogonLogoffClass
The fully qualified name of the Java Class that provides the logic to
Logon to a CICS Server using signon transactions. This property is
mandatory for signon capable terminals and for CICS servers that do
not support signon capability (such as CICS for OS/2).
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.
94 CICS Transaction Gateway: Windows Administration

Deployment parameters for the EPI resource adapter
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 signon
capable terminals (such as CICS for OS/2).
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.
Chapter 5. Configuration 95

Tracing
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.
Control of where trace is output is handled by the ConnectionManager being
used by your environment. 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 may 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}-
On Windows 2000, or Windows XP, this might map to:
C:\Documents and Settings\Administrator\IBM\CTG\-
On Windows NT this might map to:
C:\Winnt\Profiles\Administrator\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.
Sample configuration and mapping files
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. (A sample file
cicskeysamp.ini is also provided.)
cicscol.ini The color mapping file. (A sample file
cicscolsamp.ini is also provided.)
It is recommended that you create your own customized versions of these
files with different names, because installation of service updates may
overwrite the files and cause any customization to be lost.
Reference your customized files through the following environment variables:
96 CICS Transaction Gateway: Windows Administration

File Environment variable
configuration file CICSCLI
keyboard mapping file CICSKEY
color mapping file CICSCOL
Use the System icon in the Control Panel to set these environment variables.
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” on
page 96 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 page “Keyboard mapping for
CICSTERM”).
v The CICSKEY environment variable. For example:
SET CICSKEY=C:\CUSTOM\MYKEYS.INI
See your operating system documentation for other ways of setting this
environment variable.
If you do not specify otherwise, a filename 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:
Keyboard mapping file syntax
►► BIND 3270function
modifier+
Sample configuration and mapping files
key
; comment
#
►◄
Chapter 5. Configuration 97

Keyboard mapping for CICSTERM
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
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 any one of:
Alt
Ctrl
Shift
The Key can be any one of the keys shown in Table 8, (but some combinations
of modifier+key are not supported — see “Key combinations” on page 99):
Table 8. 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
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
98 CICS Transaction Gateway: Windows Administration

Table 8. Keys that you can map (continued)
Group Keys
Movement keys newline backspace
insert home pageup
delete end pagedown
up left down right
Keypad keys keypad/ keypad* keypadkeypad7
keypad8 keypad9
keypad4 keypad5 keypad6 keypad+
keypad1 keypad2 keypad3
keypad0 keypad. keypadenter
In addition, the following key mappings are allowed:
bind Clear Pause
bind Reset Scroll Lock
Keys specific to particular keyboards
Some keys are specific to particular types of keyboard.
The following additional key is unique to IBM keyboards:
rightctrl
Keyboard mapping for CICSTERM
Key combinations
The following combinations of modifier and key can be mapped:
No modifier All keys available for mapping.
Alt modifier Only function keys, numeric keys, movement
keys, and alphabetic keys can be mapped.
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.
Note: All modifier and key combinations that are not pre-empted by
Windows 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 96 for details. It is recommended that you create your own customized
mapping file.
Chapter 5. Configuration 99

Customizing the screen colors for CICSTERM
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 page “Customizing the screen
colors for CICSTERM” on page 99).
v The CICSCOL environment variable: For example:
SET CICSCOL=C:\CUSTOM\MYCOLS.INI
You can set this environment variable via the System icon in the Control
Panel.
If you do not specify otherwise, a filename 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.
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.
Notes:
1. If the color mapping file specifies a mapping for an attribute, this mapping
is used even if the hardware upon which the client is running actually
supports the screen attribute.
2. 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, then the field is displayed without any
highlighting at all.
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:
Color mapping file syntax
►► BIND 3270attrib fg_color
The file is not case-sensitive.
100 CICS Transaction Gateway: Windows Administration
/bg_color ; comment
#
►◄

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
Each of fg_color and bg_color (foreground color and background color) can be
any one of the following:
black light_gray
blue light_blue
brown yellow
cyan light_cyan
green light_green
magenta light_magenta
red light_red
gray white
If bg_color is omitted, a default value of black is taken.
Preparing to use local CICS Transaction Gateway support
Customizing the screen colors for CICSTERM
Before you can run an application that uses the local CICS Transaction
Gateway support, ensure that you have correctly configured your
environment. The following are required:
1. A correctly configured Java environment
A Java application that uses the local CICS Transaction Gateway support
is a normal Java program, and so is executed with the standard JDK Java
executable. Your environment must be correctly set so that the Java
binaries, libraries, and classes can be found. Refer to the JDK
documentation for the correct environment settings.
2. The correct settings to allow the CICS Transaction Gateway binaries to
be found
Chapter 5. Configuration 101

Preparing to use local CICS Transaction Gateway support
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. Also, the relevant
binaries must be available.
Set your PATH environment variable to include the \bin
subdirectory so that your application can find CTGJNI.DLL.
To run the application: use the JDK java command with suitable options.
102 CICS Transaction Gateway: Windows Administration

Chapter 6. Network Security
This chapter describes how to set up CICS Transaction Gateway to use the
network security protocols SSL and HTTPS. It also discusses some other
security functions relevant to Windows. This chapter consists of the following:
“Determining your use of SSLight or JSSE
for the SSL and HTTPS protocols” on
page 104
“Maintaining your digital certificates for
SSLight” on page 104
“Using externally signed certificates
under SSLight” on page 105
“Using self-signed certificates under
SSLight” on page 110
Read this for information on how CICS
Transaction Gateway determines whether
you are using SSLight or JSSE.
Read this for information on using the
IBM Key Management utility iKeyMan
for managing your digital certificates for
SSLight.
Read this for information on how to
configure an SSL server and SSL clients to
use externally signed digital certificates
under SSLight.
Read this for information on how to
configure an SSL server and SSL clients to
use self-signed digital certificates under
SSLight.
“Migration from SSLight” on page 114 Read this for information on migrating
from SSLight to JSSE.
“Installation” on page 114 Read this for information on installing
JSSE.
“Maintaining your digital certificates for
JSSE” on page 115
“Using externally signed certificates
under JSSE” on page 115
“Using self-signed certificates under JSSE”
on page 120
“Configuring CICS Transaction Gateway
for SSL and HTTPS” on page 124
Read this for information on using the
IBM Key Management utility iKeyMan
for managing your digital certificates for
JSSE.
Read this for information on how to
configure an SSL server and SSL clients to
use externally signed digital certificates
under JSSE.
Read this for information on how to
configure an SSL server and SSL clients to
use self-signed digital certificates under
JSSE.
Read this for information on how to
configure CICS Transaction Gateway to
use the secure protocols.
© Copyright IBM Corp. 1996, 2002 103

|
|
Security
“Network Provider Interface (NPI)” on
page 126
Read this for information on how to
signon to a CICS server with the same
userid and password you use to logon to
Windows NT.
Determining your use of SSLight or JSSE for the SSL and HTTPS protocols
CICS Transaction Gateway determines whether you wish to use SSLight or
JSSE as follows:
v If you pass a KeyRing class to the Gateway daemon, CICS Transaction
Gateway assumes that you are using SSLight.
v If you pass a KeyStore file to the Gateway daemon, CICS Transaction
Gateway assumes that you are using JSSE.
SSLight
Conflict with JSSE
SSLight might not function correctly if JSSE is installed on your system. If
JSSE is installed, rename file gskikm.jar, intheJRE\EXT directory.
Maintaining your digital certificates for SSLight
iKeyMan
Use the ctgikey command to invoke iKeyMan for certificate management.
With iKeyMan, you can:
v Request and receive a digital certificate from a Certification Authority (CA),
see “Using externally signed certificates under SSLight” on page 105.
v Generate self-signed certificates, see “Using self-signed certificates under
SSLight” on page 110.
v Add certificates to your KeyRing files.
v Change your KeyRing 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 KeyRing.
Distributing iKeyMan to client workstations
Although you perform most of the KeyRing management on the CICS
Transaction Gateway machine, you might need to distribute the iKeyMan tool
to clients connecting to your SSL server. The client machines must have the
104 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
Maintaining your digital certificates for SSLight
minimum level of CICS Transaction Gateway Java support; see “Supported
software” on page 22. They might also require a script or command file to
invoke the iKeyMan Java startup class.
The following is an example of a command that you can use on Windows to
invoke iKeyMan with the JDK or the JRE:
java.exe -classpath
"e:\ikeyman\cfwk.zip;e:\ikeyman\gsk5cls.jar;"
-Dkeyman.javaOnly=true com.ibm.gsk.ikeyman.Ikeyman
These examples assume that the client workstation has the following files in
the ikeyman directory:
v cfwk.zip
v cfwk.sec
v gsk5cls.jar
v ikminit.properties
All of these files are in the \classes subdirectory.
Using iKeyman in DBCS environments
If you have trouble running iKeyman in your locale, you can use this
command to run it in English:
java -classpath
"c:\Program Files\IBM\IBM CICS Transaction Gateway\classes\cfwk.zip;
c:\Program Files\IBM\IBM CICS Transaction Gateway\classes\gsk5cls.jar;"
-Dkeyman.javaOnly=true -Dkeyman.lang=en_US com.ibm.gsk.ikeyman.Ikeyman
Using externally signed certificates under SSLight
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. The following sections
describe how to configure an SSL server and SSL clients using iKeyMan.
Configuring your SSL server and clients involves:
1. Creating a KeyRing class
2. Creating a certificate request
3. Obtaining a digital certificate
4. Receiving the digital certificate into the KeyRing
Configuring your SSL server
This section describes how to obtain a Test Server Certificate from the
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a
period of 14 days. As this certificate is for demonstration only it is not signed
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All
SSL clients need the VeriSign Test signer certificate root key to be installed in
their client KeyRings, or, in the case of HTTPS connections, the repository in
Chapter 6. Network Security 105

Using externally signed certificates under SSLight
the browser. Obtaining a full VeriSign Server Certificate follows the same
procedures as described here for the test version.
1. Create a server KeyRing
The first step is to create a server KeyRing class. This will contain 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 using the command ctgikey.
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyServerKeyRing.class
e. In Location, type a suitable location to store your server KeyRing
The default location is the \bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing 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 MyServerKeyRing.class contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 108.
2. Create a Certificate Request
Before you can obtain a Server Certificate from VeriSign, you must make a
Certificate Request and store it locally:
a. From iKeyMan, select Create —> New Certificate Request.
106 CICS Transaction Gateway: Windows Administration

Using externally signed certificates under SSLight
b. Complete the certificate request. Some fields are optional, but you must
fill in at least the following (examples are shown):
Key Label verisignServerCert
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
c. Specify the name of a file in which to store the certificate request, or
accept the default.
d. Select OK.
iKeyMan generates a public/private key pair.
3. Obtain a Server Certificate
The next step is to connect to the VeriSign Web site and request a Test
Server Certificate:
a. Point your Web browser at: www.verisign.com and navigate to their
request Test Server Certificate application pages.
b. Open the certificate request file you created earlier, using an ASCII text
editor.
Figure 19 on page 108 shows an example of a certificate request.
c. During the Test Server Certificate request process you will be asked to
submit your CSR — Copy and paste the contents of the file into the
text box in the Web page.
d. Verify the contents of your certificate request and provide the personal
details when requested.
If you are requesting a full VeriSign Server ID, rather than a test
version, these details are used to authenticate your application.
e. VeriSign processes your enrollment and sends an e-mail to the address
specified in your personal details.
This e-mail contains your Test Server Certificate, and instructions on
how to:
v install a Test Server ID
v install a special Test CA Root
Chapter 6. Network Security 107

Using externally signed certificates under SSLight
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIB1jCCAT8CAQAwgZUxIDAeBgNVBAMTF2NocmlzdHAuaHVyc2xleS5pYm0u
Y29tMRswGQYDVQQLExJDbGllbnRzICsgR2F0ZXdheXMxDzANBgNVBAoTBklC
TSBVSzETMBEGA1UEBxMKV0luY2hlc3RlcjEOMAwGA1UECBMFSGFudHMxETAP
BgNVBBETCFNPMjEgMkpOMQswCQYDVQQGEwJHQjCBnzANBgkqhkiG9w0BAQEF
AAOBjQAwgYkCgYEAkAth9Ar6k6ijNZ3JxdPGH6yiikwYTuA0RZDLZBSpaSEx
4qNKN/CrdF1LgfQYbZcN5NGCeC4sC478NhT+ltf5dnR3pNWBzEzmWn5mN0lH
tqJ3oibOUmDui+tQc2J9z6iRBKjkcQwjPlJp0sp5KKsev1ahAETL7LqmqMIq
pJlzKi0CAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GBAHaMHpizPs8Q3bi3I6dh
4yw0UNhojTlS1+ffiph3hK98lMHJuMztr0UMBLl/SZGNw85OJRiWuDjGYUQW
inJ0uNH34IUsnygBmt78+WlXT5nJuayg+UrAc5Ao2H8QZpRE5Sfaoc8lQcvY
plTggCdMxpYN7I33LrZDl3Po0TT8gjxQ
-----END NEW CERTIFICATE REQUEST-----
Figure 19. Example certificate request
4. Receive the Server Certificate into the server KeyRing
When you have obtained the Server Certificate, you use iKeyMan to
receive it into the server KeyRing.
a. Copy and paste the Server Certificate data into a blank text file, using
an ASCII text editor; save the file as verisignServerID.arm.
b. From iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
c. Select Receive...
d. In the Data type pull-down, select Base64-encoded ASCII
e. Type the name and location of the text file containing your Server
Certificate data
f. Select OK.
g. Select Key Database File then Exit.
Your server KeyRing MyServerKeyRing.class is now ready for use with
CICS Transaction Gateway. It contains the default signer certificates, as
well as your VeriSign Server Certificate and its corresponding private key.
Configuring your SSL clients
In normal operation, CICS Transaction Gateway uses only server
authentication when performing an SSL handshake; the client need only
accept the presented Server Certificate. For server authentication to work, the
client KeyRing class, or in the case of HTTPS, the browser certificate
repository, must contain the signer certificate of the Server Certificate. In our
example, the signer certificate is the VeriSign Test signer certificate.
In addition to server authentication, the CICS Transaction Gateway also
supports client authentication. With this option enabled, any connection
attempted to either the ssl: or https: handler requires the client to present its
own Client Certificate, which is also known as a Digital ID.
The following sections describes how to obtain a VeriSign Digital ID.
108 CICS Transaction Gateway: Windows Administration

Using externally signed certificates under SSLight
1. Create a client KeyRing
A client KeyRing class 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 KeyRing class is similar to that for a
server:
a. Start iKeyMan using the command ctgikey
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyClientKeyRing.class
e. In Location, type a suitable location to store your client KeyRing
The default location is the \bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
h. Select OK.
Like the server KeyRing class, the client KeyRing class contains a default
selection of popular signer certificates.
2. Obtain a Client Certificate
Unlike Server Certificates, you do not need to create a certificate request to
obtain a Client Certificate. VeriSign provides a method of obtaining a Class
1 Digital ID using either Netscape or Internet Explorer browsers.
When you have obtained the Client Certificate and installed it in the
browser repository, you can export the certificate data, together with its
associated private key, into a secure file known as a #PKCS12 file. This file
is password protected and can be imported into a client KeyRing class
using the iKeyMan tool.
a. Point your Web browser at: www.verisign.com
b. Follow the links on their Web site to buy a Class 1 Digital ID from
their Secure E-Mail certificates product area.
c. Complete the enrollment form as requested. The details will be used by
VeriSign to authenticate the client application.
d. VeriSign will send information for downloading and installing the
Class 1 Digital ID to the e-mail address you supplied in your
application.
During the installation process, your browser allows you to store the
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool
supports #PKCS12 files and allows you to import certificates, along with
their private key, into a client KeyRing class.
3. Import the Client Certificate into the client KeyRing
To import the #PKCS12 file containing the Client Certificate:
Chapter 6. Network Security 109

Using externally signed certificates under SSLight
a. In iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
b. Select Import...
c. Set Key file type to PKCS12 file.
d. Type the name and location of the #PKCS12
e. Select OK.
f. Select Key Database File —> Close
g. Select Key Database File —> Exit
Your client KeyRing MyClientKeyRing.class is now ready for use with CICS
Transaction Gateway. It contains the default signer certificate, as well as your
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding
private-key.
Using self-signed certificates under SSLight
CICS Transaction Gateway provides a way for you to “self-sign” your
certificates. You establish yourself as your own Certification 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 KeyRing classes
2. creating digital certificates
3. exporting and importing the certificates
Configuring your SSL server
1. Create a server KeyRing
The first step is to create a server KeyRing class. This will contain 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 using the command ctgikey.
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyServerKeyRing.class
e. In Location, type a suitable location to store your server KeyRing
The default location is the \bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
110 CICS Transaction Gateway: Windows Administration

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 MyServerKeyRing.class contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
Using self-signed certificates under SSLight
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 108.
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 KeyRing class:
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.
Chapter 6. Network Security 111

Using self-signed certificates under SSLight
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, 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 handshake with this SSL server.
Configuring your SSL clients
1. Create a client KeyRing
A client KeyRing class 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 KeyRing class is similar to that for a
server:
a. Start iKeyMan using the command ctgikey
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyClientKeyRing.class
e. In Location, type a suitable location to store your client KeyRing
The default location is the \bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
h. Select OK.
Like the server KeyRing class, the client KeyRing class contains a default
selection of popular signer certificates.
2. Import the server’s signer certificate
a. In iKeyMan select Add
112 CICS Transaction Gateway: Windows Administration

Using self-signed certificates under SSLight
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.
If the SSL handler used by the CICS Transaction Gateway is configured to
support only server authentication, skip step 3; the client KeyRing need
contain only the signer certificate of the Server, which you have now
imported. You can use the generated MyClientKeyRing.class file with
CICS Transaction Gateway’s SSL protocol, which is configured to support
server authentication.
3. Create a Client Certificate
Client authentication requires the client KeyRing class 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. 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
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
Chapter 6. Network Security 113

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under SSLight
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 handshake with this SSL client.
Migrating old self-signed certificates
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 KeyRing class files, created with Version 3.0,
using the iKeyMan tool.
Restricting access to the server KeyRing
The contents of the server KeyRing are encrypted and protected by a
password. However IBM recommends that you:
v ensure that the KeyRing class files have appropriate security access
permissions
v restrict access, where applicable, to the CICS Transaction Gateway machine
Do not share certificates among servers. Do not allow servers to share a
private key, particularly if they are running on different machines. Never send
a private key to someone else.
Java Secure Socket Extension (JSSE)
Migration from SSLight
To avoid possible conflicts between the different versions of iKeyMan used in
SSLight and JSSE, IBM strongly recommends that you perform all migration
actions before you install JSSE.
To migrate from SSLight to JSSE:
v Create new KeyStores and use these instead of existing KeyRing classes
v Change existing security exits that implement the SSLightServerSecurity
interface to implement the JSSEServerSecurity interface
Installation
See “Supported software” on page 22 for details of environments in which
JSSE is supported.
If you do not have a supported level of JSSE on your system, you need to
install the version supplied with CICS Transaction Gateway. JSSE support is
included in two zip files supplied with the CICS Transaction Gateway
product:
v ibm-jsse.zip
114 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
v ibm-jce.zip
Copy the zip files to the jre subdirectory of your Java installation directory
on your system, and extract the archived files into this directory.
You can find the Java root directory using the command ctgjava —v. This
command displays a message like:
CCL8810I Current JVM set to: ’C:\PROGRA~1\IBM\JRE\bin\jre.exe’
In this example, the Java root directory is ’C:\PROGRA~1\IBM\JRE
Maintaining your digital certificates for JSSE
iKeyMan
Use the following command to start the iKeyMan program:
java com.ibm.ikeyman.Ikeyman
With iKeyMan, you can:
v Request and receive a digital certificate from a Certification Authority (CA),
see “Using externally signed certificates under SSLight” on page 105.
v Generate self-signed certificates, see “Using self-signed certificates under
SSLight” on page 110.
v Add certificates to your KeyStore files.
v Change your KeyStore 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 KeyStore.
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. The following sections
describe how to configure an SSL server and SSL clients using iKeyMan.
Configuring your SSL server and clients involves:
1. Creating a KeyStore
2. Creating a certificate request
3. Obtaining a digital certificate
4. Receiving the digital certificate into the KeyStore
Installing JSSE
Chapter 6. Network Security 115

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
Configuring your SSL server
This section describes how to obtain a Test Server Certificate from the
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a
period of 14 days. As this certificate is for demonstration only it is not signed
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All
SSL clients need the VeriSign Test signer certificate root key to be installed in
their client KeyStores, or, in the case of HTTPS connections, the repository in
the browser. Obtaining a full VeriSign Server Certificate follows the same
procedures as described here for the test version.
1. Create a server KeyStore
The first step is to create a server KeyStore. This will contain 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 KeyStore, such as
MyServerKeyStore.jks
e. In Location, type a suitable location to store your server KeyStore
f. Select OK
g. Type a password for the KeyStore 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 MyServerKeyStore.jks contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 118.
116 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
2. Create a Certificate Request
Before you can obtain a Server Certificate from VeriSign, you must make a
Certificate Request and store it locally:
a. From iKeyMan, select Create —> New Certificate Request.
b. Complete the certificate request. Some fields are optional, but you must
fill in at least the following (examples are shown):
Key Label verisignServerCert
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
c. Specify the name of a file in which to store the certificate request, or
accept the default.
d. Select OK.
iKeyMan generates a public/private key pair.
3. Obtain a Server Certificate
The next step is to connect to the VeriSign Web site (www.verisign.com)
and request a Test Server Certificate. You will be asked to paste in the
contents of the certificate request file you created earlier (Figure 19 on
page 108 shows an example of a certificate request) and agree to their
licensing conditions. VeriSign will then send you a confirmation e-mail.
This e-mail contains your Test Server Certificate, and instructions on how
to:
v install a Test Server ID
v install a special Test CA Root
Chapter 6. Network Security 117

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
4. Receive the Server Certificate into the server KeyStore
When you have obtained the Server Certificate, you use iKeyMan to
receive it into the server KeyStore.
a. Copy and paste the Server Certificate data into a blank text file, using
an ASCII text editor; save the file as verisignServerID.arm.
b. From iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
c. Select Receive...
d. In the Data type pull-down, select Base64-encoded ASCII
e. Type the name and location of the text file containing your Server
Certificate data
f. Select OK.
g. Select Key Database File then Exit.
Your server KeyStore MyServerKeyStore.jks is now ready for use with
CICS Transaction Gateway. It contains the default signer certificates, as
well as your VeriSign Server Certificate and its corresponding private key.
Configuring your SSL clients
In normal operation, CICS Transaction Gateway uses only server
authentication when performing an SSL handshake; the client need only
accept the presented Server Certificate. For server authentication to work, the
client KeyStore, or in the case of HTTPS, the browser certificate repository,
must contain the signer certificate of the Server Certificate. In our example,
the signer certificate is the VeriSign Test signer certificate.
In addition to server authentication, the CICS Transaction Gateway also
supports client authentication. With this option enabled, any connection
attempted to either the ssl: or https: handler requires the client to present its
own Client Certificate, which is also known as a Digital ID.
The following instructions describe how to obtain a VeriSign Digital ID.
1. Create a client KeyStore
A client KeyStore class 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 KeyStore class 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 KeyStore, such as
MyClientKeyStore.jks
e. In Location, type a suitable location to store your client KeyStore
118 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
f. Select OK
g. Type a password for the KeyStore file.
h. Select OK
Like the server KeyStore, the client KeyStore contains a default selection of
popular signer certificates.
2. Obtain a Client Certificate
Unlike Server Certificates, you do not need to create a certificate request to
obtain a Client Certificate. VeriSign provides a method of obtaining a Class
1 Digital ID using either Netscape or Internet Explorer browsers.
When you have obtained the Client Certificate and installed it in the
browser repository, you can export the certificate data, together with its
associated private key, into a secure file known as a #PKCS12 file. This file
is password protected and can be imported into a client KeyStore using
the iKeyMan tool.
a. Point your Web browser at: www.verisign.com
b. Follow the links on their Web site to buy a Class 1 Digital ID from
their Secure E-Mail certificates product area.
c. Complete the enrollment form as requested. The details will be used by
VeriSign to authenticate the client application.
d. VeriSign will send information for downloading and installing the
Class 1 Digital ID to the e-mail address you supplied in your
application.
During the installation process, your browser allows you to store the
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool
supports #PKCS12 files and allows you to import certificates, along with
their private key, into a client KeyStore.
3. Import the Client Certificate into the client KeyStore
To import the #PKCS12 file containing the Client Certificate:
a. In iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
b. Select Import...
c. Set Key file type to PKCS12 file.
d. Type the name and location of the #PKCS12
e. Select OK.
f. Select Key Database File —> Close
g. Select Key Database File —> Exit
Chapter 6. Network Security 119

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
Your client KeyStore MyClientKeyStore.jks is now ready for use with CICS
Transaction Gateway. It contains the default signer certificate, as well as your
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding
private-key.
Using self-signed certificates under JSSE
CICS Transaction Gateway provides a way for you to “self-sign” your
certificates. You establish yourself as your own Certification 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 KeyStores
2. creating digital certificates
3. exporting and importing the certificates
Configuring your SSL server
1. Create a server KeyStore
The first step is to create a server KeyStore. This will contain 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 KeyStore, such as
MyServerKeyStore.jks
e. In Location, type a suitable location to store your server KeyStore
f. Select OK
g. Type a password for the KeyStore 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 MyServerKeyStore.jks contains, by default, a selection
of popular signer certificates as follows:
120 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
Using self-signed certificates under JSSE
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 118.
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 KeyStore:
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
Chapter 6. Network Security 121

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
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, 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 handshake with this SSL server.
Configuring your SSL clients
1. Create a client KeyStore
A client KeyStore class 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 KeyStore class 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 KeyStore, such as
MyClientKeyStore.jks
e. In Location, type a suitable location to store your client KeyStore
f. Select OK
g. Type a password for the KeyStore file.
h. Select OK
Like the server KeyStore, the client KeyStore 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.
122 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
If the SSL handler used by the CICS Transaction Gateway is configured to
support only server authentication, skip step 3; the client KeyStore need
contain only the signer certificate of the Server, which you have now
imported. You can use the generated MyClientKeyStore.jks file with CICS
Transaction Gateway’s SSL protocol, which is configured to support server
authentication.
3. Create a Client Certificate
Client authentication requires the client KeyStore 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. 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
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 handshake with this SSL client.
Chapter 6. Network Security 123

|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
Migrating old self-signed certificates
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 KeyStore files, created with Version 3.0, using the
iKeyMan tool.
Restricting access to the server KeyStore
The contents of the server KeyStore are encrypted and protected by a
password. However IBM recommends that you:
v ensure that the KeyStore files have appropriate security access permissions
v restrict access, where applicable, to the CICS Transaction Gateway machine
Do not share certificates among servers. Do not allow servers to share a
private key, particularly if they are running on different machines. Never send
a private key to someone else.
Configuring CICS Transaction Gateway for SSL and HTTPS
To use the SSL and HTTPS protocols, enable them using the configuration
tool; see “Configuring CICS Transaction Gateway settings” on page 58. You
can specify that either or both of the protocols is used. When you enable the
protocols, by default, CICS Transaction Gateway listens for SSL requests on
port 8050, and for HTTPS requests on port 443.
SSL and HTTPS configuration settings
The following configuration settings are specific to the SSL and HTTPS
protocols:
KeyRing or KeyStore name Specifies the name of the server KeyRing or
KeyStore.
For a KeyRing, you must also add the
classname to the CLASSPATH environment
variable.
If your KeyRing files are in directory
e:\myKeyRings, you should specify the
CLASSPATH entry as:
e:\myKeyRings\.
(with a trailing \. after the directory name).
KeyRing or KeyStore password
Specifies the password used to read the
encrypted server KeyRing or KeyStore.
124 CICS Transaction Gateway: Windows Administration

Configuring CICS Transaction Gateway for SSL and HTTPS
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 Enables client authentication. The default is
that only server authentication is enabled.
CICS Transaction Gateway provides two default KeyRing class files,
ClientKeyRing and ServerKeyRing, that you can use to establish SSL and HTTPS
connections under SSLight. Both KeyRings have been encrypted using the
password default. Use them only in testing environments.
Specifying a client KeyRing or KeyStore
Your choice of secure protocol determines whether or not you need a
KeyRing, or KeyStore, for both server and client:
HTTPS
Specify a KeyRing or KeyStore only in the server.
SSL
The SSL protocol requires you to specify KeyRings, or KeyStores for both the
server and the client.
For more information see SSL JavaGateway, inCICS Transaction Gateway:
Programming Guide.
Using the SSL and HTTPS protocols
You use the SSL and HTTPS protocols in a similar way to the TCP and HTTP
protocols. To make a connection to CICS Transaction Gateway, your client
application flows a request using the appropriate URL. For example, for SSL
use a URL like:
ssl://transGatewayMachine:8050
Similarly, for HTTPS:
https://transGatewayMachine:443
For more information on the design and implementation of client-side
programs, see CICS Transaction Gateway: Programming Guide, and the CICS
Transaction Gateway programming interface HTML pages.
Chapter 6. Network Security 125

Network Provider Interface (NPI)
Network Provider Interface (NPI)
Network Provider Interface (NPI) allows you to signon to a CICS server using
the same userid and password that you use to log on to Windows. The CICS
server authenticates and authorizes using your domain information. This is
stored, encrypted, in memory. However, the security information remains
synchronized only if you sign on to a CICS server that supports NPI.
You enable NPI for each CICS server with the Use Windows credentials for
security configuration setting. See “Use Windows credentials for security” on
page 77 for more information.
With NPI enabled, if CICS cannot obtain the userid and password when
signing on, Windows opens a window to prompt you for the information.
Restrictions
If you run CICS Transaction Gateway as a Windows service, NPI works only
if you assign a logon user account, not the system account, to the service.
Windows allows the use of longer userids and passwords than those allowed
by CICS servers. Therefore, to use NPI, you might need to use a shorter
userid and password to logon to Windows.
126 CICS Transaction Gateway: Windows Administration

Chapter 7. Client Security
Overview
This chapter describes how to provide a userid and password when
connecting to a CICS server. It consists of the following:
“Overview” Read this for an overview of CICS
client/server security.
“Default connection settings” on page 128 Read this for information on setting
default values for userid and password.
“ECI security” on page 129 Read this for information on providing a
userid and password on an ECI request.
“EPI terminal security” on page 129 Read this for information on providing a
userid and password on an EPI request.
“Signon capable and signon incapable
terminals” on page 131
Read this for information on signon
capable and signon incapable terminals.
CICS servers may require the Client daemon to supply a userid 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 userid and
password are sent to the server in the FMH header of the transaction attach
request for each conversation. A userid and password are also required when
a signon transaction is invoked on a signon capable terminal. In this instance,
the userid and password are flowed to the server as part of the 3270
datastream.
Because the Client daemon has no security manager, it does not support
userid authentication. It is recommended that you configure your CICS server
client connections so that incoming attach requests must specify a userid and
password. For mainframe servers, specify AttachSec = Verify in the CICS
connection definition. AttachSec = Identify, which indicates that userid, but
not password, are required, is not supported for client connections.
Note: Userids and passwords must not contain DBCS characters.
© Copyright IBM Corp. 1996, 2002 127

Client Security
Default connection settings
The Client daemon maintains a default userid and password for each server
connection, which may be set by any of the following methods:
v CICSCLI security commands:
cicscli /c=servername /u=userid /p=password
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.
v From COM, use the MakeSecurityDefault method of the Connect or
Terminal COM class.
v Through a Client daemon security popup.
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.
Note: If the Client daemon is running in an environment where it survives
user logoff, for example, as a Windows service, the default userid and
password values entered by the currently logged on user are retained
even when that user logs off, and are subsequently reused as required.
Security popups
The Client daemon will display a security popup to allow the user to enter a
userid and password if ALL of the following are true:
v Terminal Services is not enabled.
v Popups are enabled in the initialization file (ctg.ini).
v The client is not running as a service, or is running as a service that is
enabled to interact with the desktop.
v The server requires that a userid and password are flowed in the
transaction attach request.
v No default security has yet been set for the server connection or default
security has been set but the settings produce a security error on the server,
for example, password expired.
v The transaction being invoked by the client is CCIN (client install) or CTIN
(terminal install).
v A terminal userid and password have not been supplied on a terminal
install request.
Values entered via a security popup, once verified, are used to set the default
userid and password values for that server connection.
128 CICS Transaction Gateway: Windows Administration

ECI security
Client Security
Security popups are not displayed directly by ECI or EPI transaction requests,
although they may be prompted by these requests, if the request causes a
server connection to be established, or a terminal to be installed.
An application may provide a userid and password on an ECI request and
these values will override any default values set for the server connection as
follows.
v C programs:
Set eci_userid and eci_password or eci_userid2 and eci_password2 in the
ECI parameter block.
v C++ programs:
Set the userid and password parameters when constructing a server
connection object - CclConn.
v COM programs:
Set the userid and password via the Details method on the Connect object.
v Java client programs:
Set the userid and password parameters when constructing an ECIRequest
object.
EPI terminal security
The Client daemon also maintains a userid and password per installed
terminal. These values will override any default values set for the server
connection. They can be set by one of the following methods:
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 COM programs:
Use the AlterSecurity method of the Terminal COM class. This can only be
used for signon incapable created terminals.
v Java client programs:
– 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.
Chapter 7. Client Security 129

Client Security
– 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.
– EPI Beans
Set the Userid and Password properties on the extended terminal
properties panel or programmatically by creating an EPI Terminal bean,
get the terminal object it holds using getTerminal() and then use
setUserid and setPassword.
v Terminal Servlet
Set pool@userid and pool@password. These settings apply to all terminals
in the pool.
Terminal security cannot be set when using the CICS CCF Connectors.
Terminal security would normally only be required if using signon incapable
terminals.
Password expiry management
For CICS clients the management of expired passwords can be handled by the
ESI functions CICS_ChangePassword and CICS_VerifyPassword. Also,
security popups will prompt specifically for any unknown userid, incorrect
password, or expired password, after the user has initially entered a userid
and password via a security popup.
The ESI functions can be used only with CICS servers that support password
expiry management (PEM). See “Supported software” on page 22, 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
SNA or TCP62. An ESM, 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 acceptable.
Network Provider Interface (NPI)
Network Provider Interface (NPI) allows you to sign on to a CICS server
using the same userid and password that you use to log onto Windows. For
more details refer to “Network Provider Interface (NPI)” on page 126.
130 CICS Transaction Gateway: Windows Administration

Signon capable and signon incapable terminals
Client Security
Signon capable terminals allow signon transactions, either CICS-supplied
(CESN) or user-written, to be run, whereas signon incapable terminals do not
allow these transactions to be run.
If a terminal resource is installed as signon capable, the application or user is
responsible for starting a signon transaction; the userid and password once
entered are embedded in the 3270 data.
v Transactions started before the signon transaction will execute with the
authorities granted to the default userid defined for the server. A check is
also done against the userid associated with the connection to see whether
the Client daemon itself has authority to access the resource.
v Transactions started after the signon transaction will execute with the
authorities granted to the authenticated userid. For transactions attempting
to access resources, security checking is done against the signed-on user’s
userid and the userid associated with the connection. If a server supports
signon timeout and a client terminal is left idle so that the timeout expires,
the user is signed off without notification and the next transaction will run
against the default userid.
If the terminal resource is installed as signon incapable, the userid and
password are authenticated for each transaction started for the terminal
resource.
Prior to Version 3.1.0 of Clients and Gateways, whether a terminal was signon
capable or not was dependant upon the server implementation. Client
terminals installed on distributed CICS servers were signon capable and
terminals installed on mainframe CICS and CICS/400 servers were signon
incapable.
In Version 3.1.0, extended EPI function was introduced to allow the signon
capability of a terminal to be specified by one of the following methods.
v C programs:
Use CICS_EpiAddExTerminal and set the SignonCapability parameter in
the CICS_EpiAttributes_t structure.
v C++ programs:
Set the signon capability parameter when constructing a CclTerminal class
object.
v COM programs:
Use the SetTermDefns method of the Terminal COM class.
v Java client programs:
– EPI Request Classes
Chapter 7. Client Security 131

Client Security
Set the signon 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 signon capability for the terminal and changes the terminal
type to extended. When you connect, you connect an extended terminal
with that signon capability. If you setSignonCapability while a terminal
is connected then it get’s saved away, it does not alter the connected
setting.
– EPI Beans
Set the SignonCapability property on the extended terminal properties
panel, or programmatically by creating an EPI Terminal bean, get the
terminal object it holds using getTerminal() and then use
setSignonCapability.
v Terminal Servlet
Assign the appropriate Signon capability string to the Servlet Property
pool@signonCapability. These settings apply to all terminals in the pool.
The signon 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 signon capability parameter in the terminal install (CTIN) response.
The signon capability of a terminal cannot be specified when using the CICS
CCF Connectors. If you are using this interface, the EPI functionality available
is unchanged from Version 3.0.x, that is, you cannot specify a userid and
password per terminal, or specify the signon capability.
To use any of the extended EPI functionality, you must ensure that you have
applied the relevant server APAR; see “CICS server PTF requirements” on
page 25.
Refer to CICS Transaction Gateway Programming Guide for further information.
Mainframe CICS servers
These servers support both signon capable and incapable terminals, provided
that they are at the prerequisite maintenance level; see “CICS server PTF
requirements” on page 25. A terminal install request that does not specify any
signon capability, for example from CICS_EpiAddTerminal, will result in a
signon incapable terminal being installed.
For signon capable terminals:
132 CICS Transaction Gateway: Windows Administration

Client Security
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 signon transaction are flowed to
the server as part of the 3270 datastream and they will therefore appear in a
client trace.
It is recommended that you 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 may fail with an EPI_ERR_SECURITY return code.
v Before the user has signed on, transactions will run under the default
userid for the CICS server. After signon, transactions will run under the
signed-on userid.
For signon incapable terminals without terminal security:
v Use the CICS_EpiAddTerminal call
v A connection userid and password will be required regardless of the setting
of the UseDfltUser in the CICS connection definition on the server.
v Transactions will run under the userid specified in the corresponding FMH
attach request.
For signon 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.
If you wish to use one of the APIs that does not support the new EPI
functionality, then you can use CRTE through a middle tier system to get
signon capable terminal-like functionality.
Chapter 7. Client Security 133

Client Security
TXSeries and CICS OS/2 servers
These servers do not support the signon capability parameter in a terminal
install (CTIN) request but will tolerate it if the required APAR is applied; see
“CICS server PTF requirements” on page 25. A terminal install request will
always result in a signon capable terminal being installed, regardless of the
signon capability requested.
CICS/400 servers
These servers do not support the signon capability parameter in a terminal
install (CTIN) request . A terminal install request will result in a signon
incapable terminal being installed, regardless of the signon capability
requested.
134 CICS Transaction Gateway: Windows Administration

Chapter 8. Performance
This chapter helps you to:
v understand the factors that affect CICS Transaction Gateway performance
v achieve the best performance from your system
“Assessing system performance” Read this for an overview of the things to
consider when assessing the performance
of your system.
“CICS Transaction Gateway
configuration” on page 136
Read this for information on CICS
Transaction Gateway configuration
parameters which affect performance.
“Java considerations” on page 138 Read this for information on Java factors
which affect performance.
“Other system factors” on page 138 Read this for information on other system
factors which affect performance.
“Tracing” on page 139 Read this for information on using tracing
to measure performance.
“Performance monitoring tools” on
page 140
Read this for information on performance
monitoring tools.
Assessing system performance
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 WebServer or Web 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.
© Copyright IBM Corp. 1996, 2002 135

CICS Transaction Gateway configuration
CICS Transaction Gateway configuration
IBM has chosen default values for configuration and tuning to give a
compromise between:
v limiting the system resources used by CICS Transaction Gateway after it
has started
v giving 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
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.
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.
If the number of threads needed by applications exceeds the value
specified for Maximum number of Connection Manager threads,
each new request that requires a Connection Manager thread must
wait until a thread becomes available. If the waiting time exceeds the
value specified in the Connection timeout parameter, CICS
Transaction Gateway refuses the connection.
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
136 CICS Transaction Gateway: Windows Administration

CICS Transaction Gateway configuration
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
v If the value is too low, CICS Transaction Gateway uses resources to
search for available Worker threads.
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 number of transactions per second passing through CICS
Transaction Gateway
v average transaction response time through CICS Transaction
Gateway in seconds
Communication protocols
Your choice of protocol depends on the nature of your client
applications. However, CICS Transaction Gateway does considerably
more processing to handle the HTTP and HTTPS protocols than it
does to handle the TCP and SSL protocols. In addition, when using
HTTP or HTTPS, CICS Transaction Gateway creates a new TCP/IP
connection with each client request. For better performance, use TCP
or SSL in preference to HTTP or HTTPS where possible.
Display TCP/IP hostnames
Selecting this option might cause severe performance reduction on
some systems. See “Display TCP/IP hostnames” on page 60.
Timeout values
It is unlikely that you can improve performance by changing the
default timeout values. However, you may need to change them for
particular applications. Refer to “Configuring CICS Transaction
Gateway settings” on page 58 for more information on these and all
other configuration parameters.
Connection logging
The gateway configuration setting, Log 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 client
connections and disconnections” on page 61.
Chapter 8. Performance 137

Java considerations
Java considerations
Other system factors
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; see
also “java.lang.OutOfMemory exception” on page 217. 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 is enabled by default in JDK 1.3.1. Performance
immediately after a CICS Transaction Gateway has started might be
relatively slow because of JIT overheads. The JIT threshold is 2000 on
JDK 1.3.1 compared with 500 on JDK 1.1.8; that is, each method has to
run 2000 times before it is ’JITed‘. 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 may be small , and the amount of data expected from CICS in
return may 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.
138 CICS Transaction Gateway: Windows Administration

Tracing
Other system factors
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 Do not use the deprecated setCommareaInboundLength method
because it prevents automatic commarea null stripping.
CICS server transactions
The design of your CICS server transactions affects the performance of
your system. The response time through 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, 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 may 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 may 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.
IBM does not recommend the use of the full CICS Transaction Gateway trace
to monitor performance in a production environment. This is because the
trace itself significantly decreases performance.
Chapter 8. Performance 139

Tracing
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 client application, and also
through CICS and WebSphere.
Performance monitoring tools
Performance Monitor (perfmon)
This utility is available on Windows. Refer to the documentation for
your operating system for more information.
Refer also to the performance and tuning documentation for WebSphere, SNA,
TCP/IP, CICS Transaction Server for z/OS, and TXSeries.
140 CICS Transaction Gateway: Windows Administration

Chapter 9. Operating the Gateway
This chapter describes how to operate the Gateway daemon of CICS
Transaction Gateway. It consists of the following:
“Before you start” Read this for information on the
privileges that a user needs to operate
CICS Transaction Gateway.
“Starting the Gateway” Read this for information on starting
CICS Transaction Gateway.
“Stopping the Gateway” on page 144 Read this for information on stopping
CICS Transaction Gateway.
“Running CICS Transaction Gateway as a
Windows service” on page 146
Read this for information on running
CICS Transaction Gateway as a Windows
service
“Administering your system” on page 149 Read this for information on setting the
Gateway and JNI traces, and querying
trace settings.
Before you start
To operate CICS Transaction Gateway, you must log in either as an
administrator, or as a user with the following privileges:
v network access through TCP/IP
v read access to file CTG.INI
v read access to the directory in which you installed CICS Transaction
Gateway
Starting the Gateway
You start the Gateway at the operating system command prompt of the
computer on which you have installed it.
First, set your working directory to the \bin subdirectory.
You can start the CICS Transaction Gateway in two ways:
v “Starting the Gateway with preset options” on page 142
v “Starting the Gateway with user-specified options” on page 142.
© Copyright IBM Corp. 1996, 2002 141

|
Starting the Gateway with preset options
To start the Gateway with predefined options: Type ctgstart at the command
prompt and press Enter, or select the CICS Transaction Gateway icon. This
command runs the Gateway with the JVM specified by the ctgjava command.
When you start the Gateway like this the values you configured using the
configuration tool are used. (see “Using the configuration tool” on
page 54).The gateway will not start without a valid INI file.
A Gateway console session starts, and the following messages are displayed
showing the values being used for TCP/IP:
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345
Starting the Gateway with user-specified options
The user-definable options on the start command are:
-port=port_number
-initconnect=number
-maxconnect=number
-initworker=number
-maxworker=number
-trace
-noinput
-tfile=pathname
-x
-tfilesize=number
-truncationsize=number
-dnsnames
-dumpoffset=number
-stack
-jargument to pass to the JVM
where:
-port
Specifies the TCP/IP port number which the gateway will listen on.
-initconnect
Specifies an initial number of ConnectionManager threads.
-maxconnect
Specifies a maximum number of ConnectionManager threads. If you set
this value to -1, no limits are applied to the number of
ConnectionManager threads.
-initworker
Specifies an initial number of Worker threads.
-maxworker
Specifies a maximum number of Worker threads. If you set this value to
-1, no limits are applied to the number of ConnectionManager threads.
142 CICS Transaction Gateway: Windows Administration

-trace
Enables standard tracing (see “Tracing” on page 209). 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 codepage, is shown at the top of
the trace output.
If you used the configuration tool to configure CICS Transaction Gateway,
the default destination for the trace output is file ctg.trc in the
\bin subdirectory. Otherwise, trace output is written to
stderr.
-noinput
Disables the reading of input from the console.
-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 209). 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 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, then no data blocks are shown in the trace.
-dnsnames
Enables the display of symbolic TCP/IP hostnames in messages. See
“Display TCP/IP hostnames” on page 60 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 209). Java
exceptions are traced, including those which are expected during normal
operation of the Gateway. No other trace output is created. See the -trace
and -tfile options for information on the destination for trace output.
Chapter 9. Operating the Gateway 143

|
|
|
|
-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 switch. This replaces the -X switch used in versions
of the CICS Transaction Gateway prior to 5.0.
To override the startup defaults type ctgstart at the command prompt,
followed by the start-up options you require, and press Enter. Options
specified on the command line override those specified using the configuration
tool.
A Gateway console session starts, and the following messages are displayed
showing the values being used for TCP/IP:
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345
To get help on the startup options, enter:
ctgstart -?
Stopping the Gateway
To stop the Gateway:
v If you did not start the Gateway with the -noinput option, you can stop it
by typing the correct character and pressing the Enter key in the Gateway
console session. The allowable characters may be localized for your country;
the default characters allowed are the Q or - characters.
You can determine which characters will stop the Gateway by simply
pressing the Enter key in the Gateway console session. A message like the
following is displayed:
CCL6508I: Type Q or - to stop the CICS Transaction Gateway.
v If you used the -noinput option, you must stop the Gateway process using
some other method, for example:
– Enter Ctrl-C in the Gateway console session
– Use theWindows Task Manager
Note: If you try to close the CICS Transaction Gateway console window by
using either the ’X’ close-window icon, or the Close menu item, a Full
thread dump is produced. This is an effect common to all Java
applications, including the CICS Transaction Gateway.
The CICS Transaction Gateway icons
The CICS Transaction Gateway is supplied with the following Start Menu
shortcuts:
144 CICS Transaction Gateway: Windows Administration

IBM CICS Transaction Gateway
Starts the Gateway daemon according to the definitions in the
configuration file.
This is equivalent to the command CTGSTART
The Client daemon is automatically run when this icon is
used.
Start Client Starts the Client daemon according to the definitions in the
configuration file.
This is equivalent to the command CICSCLI /s /w
Stop Client Stops the Client daemon.
This is equivalent to the command CICSCLI /x /w
Client Status Lists connected servers.
This is equivalent to the command CICSCLI /l /w
Config Tool Runs the configuration tool which provides a graphical user
interface for editing the configuration file.
CICS Terminal
Starts a 3270 terminal emulation session according to
definitions in the configuration file.
This is equivalent to the command CICSTERM /s
CICS Printer Displays help information for CICS print terminal emulation.
This is equivalent to the command CICSPRNT /?
iKeyMan This runs the IBM Key Management program which allows
you to modify your key database content.
Documentation
Opens up the PDF Documentation library file which contains
the manuals relating to the CICS Transaction Gateway.
Programming Reference
Opens the Java Programming Reference HTML in your default
browser.
ReadMe Displays the CICS Transaction Gateway Readme file in your
default text file viewer.
See “Creating Start Menu shortcuts” on page 36 for instructions on how to
create additional Start Menu shortcuts
Chapter 9. Operating the Gateway 145

Running CICS Transaction Gateway as a Windows service
When you install CICS Transaction Gateway, the daemon process is installed
as a Windows service. Running CICS Transaction Gateway as a Windows
service has several advantages:
v You can have the CICS Transaction Gateway service started automatically at
Windows startup, without having to log on to the computer.
v You can log off from Windows and keep CICS Transaction Gateway
running, thereby avoiding restarting the CICS Transaction Gateway and its
connection to CICS when you log on to Windows again.
v Relevant messages associated with running CICS Transaction Gateway as a
service are recorded in the Application log and System log of the Windows
Event Viewer when the service is started and stopped.
IBM recommends that you run the CICS Transaction Gateway service as either
System (Administrator), or as a user with the log on as a service right in a
secured environment.
CICS Transaction Gateway is registered as a Windows service during
installation. After installation, the Services dialog box in the Control Panel
contains the CICS Transaction Gateway service.
There is also a utility, ctgservice, that allows you to remove and install the
CICS Transaction Gateway service.
Windows Client daemon is also registered as a Windows service during
installation, for more information, see “Client daemon service” on page 149.
Starting and stopping the service
To start the CICS Transaction Gateway service, select the service in the
Services dialog box, and select Start. A message is displayed and the service is
started.
To stop the CICS Transaction Gateway service, select the service in the
Services dialog box, and select Stop. A message is displayed and the service is
stopped.
Startup options for the CICS Transaction Gateway service
IBM recommends that you start the CICS Transaction Gateway service
automatically at Windows startup, so that it is always running.
Note: You must have Administrator authority to configure service startup.
To specify automatic startup on Windows NT:
1. Select the service in the services dialog.
146 CICS Transaction Gateway: Windows Administration

2. Select Startup in the Services dialog box. The Service panel is then
displayed.
3. Select the Automatic radio button, and make sure that the System
Account radio button is selected.
The Service panel also allows you to specify a Manual startup for the service,
and to disable the service.
To specify automatic startup on Windows 2000 and Windows XP :
1. Select the service in the services dialog.
2. From the menu bar select Action –> Properties.
3. Change the Startup type to Automatic.
4. Select the Log On tab.
5. Make sure that the Local System Account radio button is selected.
The Service panel also allows you to specify a Manual startup for the service,
and to disable the service.
For more information on services and their configuration, refer to the
Windows documentation.
CICS Transaction Gateway service and console messages
The CICS Transaction Gateway service reports only standard Windows service
messages to the system application log.
Like other Windows services, when the CICS Transaction Gateway service is
running, no console output is available. This means that CICS Transaction
Gateway trace and debug messages will not be available as console output.
However, you can overcome this problem by specifying the ctgstart -tfile
option, which allows redirection of trace messages to a text file.
When installing the CICS Transaction Gateway service, you should ensure
that the -noinput command line option is passed. By default, the Gateway
checks Standard.in() for keyboard input (such as ″Q″ to stop the Gateway).
The default setting will throw an exception in the Gateway code, as
Standard.in() is not available when running as a service.
The ctgservice utility
The ctgservice utility allows you to install and remove the CICS Transaction
Gateway service, and pass startup options to the ctgstart command.
The ctgservice utility uses the JVM specified by the ctgjava command, see “Set
the JVM” on page 52.
The syntax of ctgservice is as follows:
Chapter 9. Operating the Gateway 147

|
ctgservice [-i] [-r] [-c] [?]
[-ACTGParam1 -ACTGParam2...]
where:
-i Installs the CICS Transaction Gateway service.
-r Removes the CICS Transaction Gateway service.
-c Runs the CICS Transaction Gateway as a console application, that is, the
CICS Transaction Gateway will run in a console window as it does when
started with the ctgstart command. If you do not specify this option, you
will not see any console messages.
-? Displays help information for ctgservice.
-A Specifies an option to be passed to the ctgstart command. All ctgstart
command line options can be passed. Each option must be prefixed with
-A. Note that the -noinput option is always required when running the
CICS Transaction Gateway as a service. This prevents standard input from
being read by the Java application, which could cause an exception.
The following is a typical example of a ctgservice command:
ctgservice -i
-A-noinput -A-x -A-tfile="e:\theGateway\myTrace.txt"
This example would install the CICS Transaction Gateway and specify the
-noinput, -x and -tfile options for the ctgstart command.
Note: Because the Windows service runs under the system account, it may
not have sufficient access privileges to write to a network file. If this is
so, then any pathname that you specify in the -tfile option must be for
a local file.
You can test the CICS Transaction Gateway and ctgstart options by running
the service in ″console″ mode. The service must already be installed on the
system. The command ctgservice -c will then run the CICS Transaction
Gateway in the console window (identical in operation to running the normal
ctgstart script), using the values it was installed with. These values are stored
statically in the Windows registry.
Note: If you find that the message:
IBM CICS Transaction Gateway error: 0,
Cannot create Java Virtual Machine
is displayed when you run ctgservice, this is probably because you
have a JVM referenced in the PATH setting before the JVM required by
the CICS Transaction Gateway. Make sure that your PATH setting
148 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
includes the bin directory of the supported level of Java that you are
using, before any other JVM references.
Running as a Windows service under Java 1.3.0
Java 1.3.0 does not survive a Windows logoff, and so any Java applications
running cease at logoff. This is a known issue, and affects the CICS
Transaction Gateway. To overcome it, pass the -j-Xrs parameter to Java when
running the application. If you used the Gateway Installer to install the
Windows services, the Gateway service will be set up to run with this flag
and the services will work correctly. However, if you install the Gateway
service manually, using the ctgservice command, you must include the -j-Xrs
parameter:
ctgservice -i -A-j-Xrs
Client daemon service
The CICS Transaction Gateway service requires that the Client daemon service
is installed and started, therefore:
v Starting the CICS Transaction Gateway service (via the Control Panel)
results in the Client daemon service starting.
v Stopping the Client daemon service (via the Control Panel) results in the
CICS Transaction Gateway service also stopping.
Administering your system
If you enabled the TCPAdmin protocol (see “TCPAdmin protocol settings” on
page 69), you can perform the following administrative functions without
having to restart the CICS Transaction Gateway:
v Set the Gateway trace
v Set JNI trace
v Query the current trace settings
You execute the Java archive ctgadmin.jar from a command prompt to set
trace or to query trace settings. You can administer the CICS Transaction
Gateway remotely from a workstation that has this JAR file and the supported
level of Java; you do not need to install the CICS Transaction Gateway on the
workstation. See “TCPAdmin protocol settings” on page 69 for details of how
to define which hosts have permission to administer your CICS Transaction
Gateway.
The following sections describe the commands. Parameters are not case
sensitive; those in brackets are optional.
Warning: Do not specify a CICS Transaction Gateway earlier than version 5.0.
Earlier versions cause the administration program to lock. If this
happens, terminate the process, for example by pressing Ctrl+C.
Chapter 9. Operating the Gateway 149

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Administering your system
Setting the Gateway trace
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address -a=setgwtrace [-tfile=path]
[-tfilesize=number] [-tlevel=number]
[[-truncationsize=number][-dumpoffset=number]|-fulldatadump]
See “Parameters” for an explanation of parameters.
Setting the JNI trace
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address
-a=setjnitrace -tfile=path [-tlevel=number]
See “Parameters” for an explanation of parameters.
Querying trace settings
From a command prompt, issue the following command:
Parameters
java -jar ctgadmin.jar -ctg=address -a=qtrace
See “Parameters” for an explanation of parameters.
ctg Mandatory. Specifies the Gateway which is to be
administered. You can specify either a hostname, for example
tcp://myserver:2810, or an IP address, for example
tcp://127.0.0.1:2810. In these examples, 2810 is the port you
specified for TCPAdmin; see “TCPAdmin protocol settings” on
page 69.
Warning: Do not specify a CICS Transaction Gateway earlier
than version 5.0. Earlier versions cause the
administration program to lock. If this happens,
terminate the process, for example by pressing
Ctrl+C.
a Mandatory. Defines the action to take. Permitted values are:
v setgwtrace to control Gateway tracing
v setjnitrace to control JNI tracing
v qtrace to determine what trace settings are active
tfile Specifies the output file for Gateway or JNI tracing, for
example ./tracefile.trc. Do not specify the same file for
Gateway and JNI trace output.
Gateway tracing
If you do not specify a value for this tag, trace output is
sent to the console.
150 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Administering your system
JNI tracing
You must specify a value for this tag. If you do not, an
error is displayed.
tlevel Specifies the trace level. Permitted values are:
Gateway tracing:
0 Off. No trace information is output.
1 Exception tracing. Only exceptions are traced.
Equivalent to ctgstart -stack; see “Starting the
Gateway with user-specified options” on page 142.
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).
JNI tracing:
0 Off. No trace information is output.
1 On.
tfilesize Specifies the maximum size, in kilobytes, of the trace output
file, for example 50000.
dumpoffset 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. You
cannot use this together with the fulldatadump parameter.
truncationsize 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 parameter.
fulldatadump Sets the dumpoffset to 0 and ignores any value specified in
truncationsize.
Chapter 9. Operating the Gateway 151

Administering your system
152 CICS Transaction Gateway: Windows Administration

Chapter 10. Operating the Client daemon
This chapter describes how to operate the Client daemon. It consists of the
following:
“The CICSCLI command” Read this for an introduction to the Client
daemon command.
“Running the Client daemon as a
Windows service”
Read this for information on running the
Client daemon as a Windows service
“The CICSCLI command” on page 156 Read this for information on using the
CICSCLI command to control the Client
daemon.
“CICSCLI command reference” on
page 160
Read this for a detailed reference to the
CICSCLI command.
The CICSCLI command
The CICSCLI command is used to start and stop 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
use the CICSCLI command to start the Client daemon explicitly.
You must explicitly terminate any server connections initiated by ECI calls. To
do this, use the CICSCLI -x=servername or CICSCLI -i=servername command.
See “CICSCLI command reference” on page 160.
Running the Client daemon as a Windows service
You can run the Client daemon as a Windows service. This has several
advantages:
v You can choose to start the Client daemon automatically at Windows
startup, without having to log on to the computer.
v You can log off from Windows and keep the Client daemon running. This
avoids the need to restart the Client daemon and its connection to CICS
when you log on to Windows again.
v Error messages associated with running the Client daemon as a service are
recorded in the Application log and System log, of the Windows Event Viewer,
when the service is started and stopped.
© Copyright IBM Corp. 1996, 2002 153

Running the Client daemon as a Windows service
It is recommended that you start the Client daemon as a service if running
under Windows 2000 Terminal Services. This is because, if a user’s application
starts the Client daemon, and that user then logs off, the Client daemon
process terminates.
The Client daemon is registered as a Windows service during installation.
After installation, the Services dialog box in the Control Panel contains the
IBM CICS Transaction Gateway and IBM CICS Universal Client services.
Service controls
You can use the Windows service API functions to pass service control
requests to the Client daemon service. Refer to your Windows documentation
for further details about how to do this.
The control requests that you can pass to the Client daemon service are
defined in the cicsserv.h file in the \ include subdirectory.
The following are the control requests that you can pass to the Client daemon
service.
Control Request Description
CICS_SRV_STOP Stops the Client daemon. This also stops the
service.
CICS_SRV_STOP_IMMEDIATE
Forces the Client daemon to terminate
immediately. This also stops the service.
CICS_SRV_LIST Lists the servers to which the Client daemon
is currently connected.
CICS_SRV_DISK_TRACE_ON
Starts writing trace information to the
CICSCLI.BIN file in the \bin
subdirectory.
CICS_SRV_DISABLE_POPUP
Suppresses error and security popups for the
Client daemon.
CICS_SRV_ENABLE_POPUP Activates error and security popups for the
Client daemon.
CICS_SRV_QUIET Suppresses all Client daemon messages.
In addition to these control requests, you can also pass standard Windows
requests to the service, such as: SERVICE_CONTROL_STOP,
SERVICE_CONTROL_PAUSE, SERVICE_CONTROL_CONTINUE, and
SERVICE_CONTROL_INTERROGATE.
154 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Service startup parameters
If you run the Client daemon as a service, you can use the Windows service
control panel to pass parameters to the service when starting from the dialog.
The following parameters are valid:
-S[=server] Starts the Client daemon, and optionally connects to a server.
-D[=size] Enables service tracing, and optionally sets a size limit.
-U[=userid] Sets the userid to be used with a server.
-P[=password] Sets the password to be used with a server.
-N Suppresses error and security popups for the Client daemon.
-R[=filename] Redirects all output for the Client daemon to the specified file.
Starting and stopping the service
To start the Client daemon service, select the service in the Services dialog
box, and select Start. A message displays and the service starts.
To stop the Client daemon service, select the service in the Services dialog
box, and select Stop. A message displays and the service stops.
Starting the Client daemon service at Windows startup
You can choose to start the Client daemon service automatically at Windows
startup.
To specify automatic startup:
Running the Client daemon as a Windows service
Windows 2000 and Windows XP
1. Log in as a user with Administrator authority.
2. Open the Services dialog box, right-click the IBM CICS Transaction
Gateway service, and select Properties.
3. Change Startup type to Automatic.
4. Select the Log On tab, and make sure that the Local System account radio
button is selected.
Windows NT
1. Log in as a user with Administrator authority.
2. Open the Services dialog box and select the IBM CICS Transaction
Gateway service.
3. Select Startup... in the Services dialog box; the Service panel is displayed.
4. Select the Automatic radio button.
5. Make sure that the System Account radio button is selected.
Chapter 10. Operating the Client daemon 155

|
|
|
|
Running the Client daemon as a Windows service
The Service panel also allows you to specify a Manual startup for the service,
and to disable the service.
For more information on services and their configuration, refer to your
Windows documentation.
The CICSCLI command
The following table shows the functions that you can perform with the
CICSCLI command, and the parameters associated with each function:
Function Parameters
Start the Client daemon, and start communication with CICS
servers
-s
Stop the Client daemon -i and -x
Restart the Client daemon -j and -y
Start client tracing -d
Stop client tracing -o
Specify the client components to be traced -m
Set up security -c, -u, and -p
List connected CICS servers -l
Enable the display of pop-up messages -e
Disable the display of pop-up messages -n
Wait for confirmation before completion -w
Display information about the version and build level of the Client
daemon
-v
The following sections provide examples of using the CICSCLI command. Full
details of the command syntax are in “CICSCLI command reference” on
page 160.
Starting the Client daemon
To start the Client daemon, enter:
CICSCLI -s
or use the Start Client shortcut.
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.
156 CICS Transaction Gateway: Windows Administration

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 the CICS connection definition, you
must stop and restart the connection.
Stopping the Client daemon in a controlled manner
To stop the Client daemon for all connected servers, after all outstanding units
of work have completed, enter:
CICSCLI -x
or use the Stop Client shortcut.
To terminate 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 stop the Client daemon or connections to
other servers.
Note:
If you want to stop and restart the Client daemon, you must first stop
the Gateway daemon. Failure to do so causes both the Gateway
daemon and the Client daemon to behave unpredictably. When the
Gateway daemon has stopped, you can stop and restart the Client
daemon before restarting the Gateway daemon.
Stopping the Client daemon immediately
To stop the Client daemon for all connected servers, without completing
outstanding units of work, enter:
CICSCLI -i
To terminate the session with a particular server, enter:
CICSCLI -i=servername
The CICSCLI command
where servername is the name of a CICS server. This stops only the session
with the named server; it does not stop the Client daemon or connections to
other servers.
Chapter 10. Operating the Client daemon 157

The CICSCLI command
Restarting the Client daemon in a controlled manner
To stop 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.
Restarting the Client daemon immediately
To stop 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.
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
parameters together.
The Client daemon writes trace entries to the CICSCLI.BIN file in the
\bin 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.
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 160.
Stopping client tracing
To stop tracing the Client daemon, enter:
CICSCLI -o
Setting up security
You can use the following commands after first starting the Client daemon.
To set a userid to use when accessing server servername, enter:
CICSCLI -c=servername -u=userid
158 CICS Transaction Gateway: Windows Administration

where userid is the userid and servername is the servername.
To set a password to use when accessing server servername, enter:
CICSCLI -c=servername -p=password
where password is the password and servername is the name of the server.
You can enter the -u and -p parameters together.
Version information
To display information about the version and build level of your Client
daemon, enter the command
CICSCLI -v
The Client daemon displays information similar to Figure 20:
CCL8001I CICSCLI - CICS Client Control Program
CCL0002I (C) Copyright IBM Corporation 1994, 2002. All rights reserved.
CCL8029I CICS Client for Windows Version 5.0 Service Level 00
CCL8074I Build Level ’c000-20020510a’
CCL8025I The CICS Client has not been started
CCL8023I CICSCLI performed no action
Figure 20. Version and build level information for the Client daemon
Listing the connected servers
To list all the servers being used by the Client daemon, and their status, enter:
CICSCLI -l
or use the Client Status shortcut.
The CICSCLI control program displays information similar to Figure 21:
CCL8001I CICSCLI - CICS Client Control Program
CCL0002I (C) Copyright IBM Corporation 1994,2002. All rights reserved.
CCL8041I The CICS client is using the following servers:
CCL8042I Server ’CICSWIN’ (using ’TCP/IP’ to ’CICSWIN’) is available
Figure 21. Example list of CICS servers
Disabling the display of messages
To disable the display of all messages output with the command, enter, for
example:
CICSCLI -s -q
Enabling and disabling the display of pop-up messages
To disable the display of pop-up messages, enter:
CICSCLI -n
The CICSCLI command
Chapter 10. Operating the Client daemon 159

The CICSCLI command
To enable the display of pop-up messages again, enter:
CICSCLI -e
You can specify the -n parameter together with the -s parameter.
The display of pop-up messages is enabled by default.
Displaying the command parameters
To display the parameters of the CICSCLI command, enter:
CICSCLI -?
The CICSCLI command and applications
You can call CICSCLI from within applications, if this is supported by the
programming language. You can therefore enter CICSCLI at the command
line, then run an application to call CICSCLI with additional parameters.
Alternative to CICSCLI.EXE
CICSCLIW.EXE performs the same functions as CICSCLI. However, it is a
Windows program that issues all of its messages into a dialog box, rather than
the command prompt. Use it if you want the Client daemon to behave in the
same way as the CICS Client for Windows 3.11 v2.
CICSCLI command reference
To conform with other popular syntax conventions, the dash (-) may be
replaced with the forward slash (/) character. The commands and options are
not case-sensitive.
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.
For an explanation of syntax diagrams, see “Conventions and terminology
used in this book” on page x.
CICSCLI Command Syntax
160 CICS Transaction Gateway: Windows Administration

►► CICSCLI -s
-s=servername -d -m -n
-d=nnn -m=components
-o
-d
-d=nnn
-m
-m=components
-x
-x=servername
-i
-i=servername
-l
-j
-y
-c=servername
-u=userid -p=password
-u -p
-e
-n
-?
The CICSCLI command
The options are:
-c=servername Identifies the name of the server to which security information
in the form of a userid 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
userid and password, unless these have already been
provided via CICSCLI (see the descriptions of 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.
The Client daemon writes trace entries to the CICSCLI.BIN file
in the \bin 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 222.
-q
-w
Chapter 10. Operating the Client daemon 161
►◄

The CICSCLI command
-e Enables the display of Client daemon error and security
messages in pop-up windows.
-i Stops the Client daemon immediately. The options
-i=servername and -i operate as for -x=servername and -x
respectively but the Client daemon does not wait for
outstanding units of work to complete. Stopping the Client
daemon in this way may result in a loss of data at connected
servers.
-j Stops 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.
Using -y is the preferred way of restarting the Client daemon.
-l Causes a list of all connected servers to be displayed. 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:
ALL All components
API.1 The client API layer (level 1). This gives basic
API tracing.
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.
162 CICS Transaction Gateway: Windows Administration

The CICSCLI command
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
LMG The Workload Manager
SER The Client daemon Windows service
TRN Interprocess communication
For guidance on when to use the tracing options, see
“Choosing which components to trace” on page 221.
The -m parameter 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 you must specify
the -s parameter before you use -m.
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 86 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,
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.
For the API and DRV components, you can specify the level
of information to trace. For example components API or API.1
specify that basic API-related information is traced before and
after ECI and EPI calls. Component API.2 specifies that
additional API trace entries are produced in addition to those
of level 1.
Note that the CICSCLI -d=nnn command is used to set the
maximum size of the data areas to be traced. The trace data
may be truncated if you set nnn lower than the size of data
expected.
Chapter 10. Operating the Client daemon 163

The CICSCLI command
-n Disables the display of Client daemon error and security
messages in pop-up windows.
Any messages that would have been logged are still logged.
-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 parameter. (Or by the -s parameter.)
This password is used if the server requires a password (and
userid) before running transactions on the client’s behalf.
For ECI applications, any userid and password specified in
the ECI parameter block overrides values set via 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 output with 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 exist in the configuration file.
-u=userid Sets the current userid to be used when accessing the server
specified by the -c parameter. (Or by the -s parameter.) This
userid is used if the server requires a userid (and password)
before running transactions for the Client daemon.
For ECI applications, any userid and password specified in
the ECI parameter block overrides values set via the CICSCLI
command.
Specifying -u or -u= (that is, no userid is specified) resets the
associated userid 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 messages output to the screen (both
informational and error) have been read.
-x Stops the Client daemon in a controlled manner. If
-x=servername is specified, then when all outstanding units of
work on the specified server have completed, the connection
to the server is terminated. If other server connections are
active, these remain unchanged.
164 CICS Transaction Gateway: Windows Administration

The CICSCLI command
If -x is specified without a servername, 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 in a controlled manner.
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 re-established when the Client daemon is
restarted.
Using -y is the preferred way of restarting the Client daemon.
-? Causes the command syntax to be displayed.
Note: The -f parameter is no longer supported. See “Using the configuration
tool” on page 54 for information on how to specify a configuration file.
Chapter 10. Operating the Client daemon 165

The CICSCLI command
166 CICS Transaction Gateway: Windows Administration

Chapter 11. Terminal Emulation
This chapter describes how to use the CICSTERM and CICSPRNT programs.
It consists of the following:
“Summary of Terminal Emulation
commands”
“CICSTERM command reference” on
page 169
“Terminal emulator preferences” on
page 172
Read this for a summary of the
commands explained in this chapter.
Read this for a detailed reference to the
CICSTERM command.
Read this for information on setting
preferences for the terminal emulator.
“The CICSPRNT command” on page 173 Read this for information on using the
CICSPRNT command to control 3270
printer terminal emulation.
“CICSPRNT command reference” on
page 175
Summary of Terminal Emulation commands
Read this for a detailed reference to the
CICSPRNT 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
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 CICSTERM command detects whether the hardware on which the Client
daemon is running is enabled for double-byte character set (DBCS) display. If
it is, the emulator can display DBCS characters.
For CICSTERM emulators, the maximum screen size is 27 rows by 132
columns. This is because the Client daemon supports the ASCII-7 subset of
© Copyright IBM Corp. 1996, 2002 167

The CICSTERM command
the 3270 data stream architecture, which supports only 12 bit addressing. For
more information, see CICS Transaction Gateway: Programming Guide.
Note: Some uses of servers and protocols require a model terminal definition
for the emulator that explicitly specifies that the Client daemon wants
to display DBCS.
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 signon incapable -a
Determine the print file processing -p
Specify a file to which print files are appended -f
CICSTERM command once with all the parameters you require.
The following is an example of a CICSTERM command:
CICSTERM -s=CICSOS2 -t=CESN -k=mykeys.ini -c=mycols.ini
-n=cicsv123 -f=clprint.txt -q
In this example:
-s=CICSOS2 Specifies that a 3270 terminal emulator is started for the server
CICSOS2.
-t=CESN Specifies that the initial transaction is CESN.
-k=mykeys.ini Specifies that the keyboard mapping file is named as
mykeys.ini.
-c=mycols.ini Specifies that the color mapping file is named as mycols.ini.
-n=cicsv123 Specifies that the 3270 terminal emulator characteristics are
defined by the terminal definition cicsv123.
-f=clprint.txt Specifies that the print file will be appended to the file
clprint.txt.
168 CICS Transaction Gateway: Windows Administration

-q Specifies that the display of messages output by the command
is disabled.
All parameters of CICSTERM are optional. That is, you can enter the
CICSTERM command without any parameters, and defaults are taken from
the configuration file. This is equivalent to using the CICS Terminal shortcut.
Full details of the parameters are given in “CICSTERM command reference”.
Stopping a terminal emulator
To stop a terminal emulator, enter, from an empty terminal screen, the string
specified by the Terminal exit configuration setting, and 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 straight away 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.
CICSTERM command reference
For an explanation of syntax diagrams, see “Conventions and terminology
used in this book” on page x.
CICSTERM Command Syntax
►► CICSTERM
-s = servername -t=initialtransid
-s -t
-r=servername
-r
The CICSTERM command
Chapter 11. Terminal Emulation 169
►

The CICSTERM command
►
►
-k=keyfile -c=colorfile -m=modelname -a
-c -m
-n=netname -p=printcmd -q -?
-f=printfile -w
The options are:
-a Specifies that the terminal emulator is not signon capable. By default,
CICSTERM creates terminal emulators that are signon capable.
For more information on signon 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 99 for more details. If you omit this parameter, the environment
variable CICSCOL is assumed to identify the color mapping file. If
CICSCOL is not defined, a filename of cicscol.ini in the
\bin subdirectory is assumed.
If the parameter is specified as -c=, that is, the color mapping filename
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 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 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 97 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 filename 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
170 CICS Transaction Gateway: Windows Administration
►
►◄

The CICSTERM command
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. For example, on CICS for OS/2 it
references a termid defined in the CICS tables, but on TXSeries for
AIX it is a netname.
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, then
the command must be enclosed 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 filename
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 terminal emulator 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
Chapter 11. Terminal Emulation 171

The CICSTERM command
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 terminal. 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.
This option is case sensitive.
Note: Be careful that transactions that you specify either here or in
the configuration file do not require terminal input to complete.
-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.
Terminal emulator preferences
The terminal emulator allows you to choose a font, by clicking Settings →
Font. IftheSettings → Save on exit menu option is selected, your choices are
stored in CICSTERM.INI, for use in future sessions. A copy of CICSTERM.INI
is created for each Windows user account as follows:
On Windows NT:
c:\profiles\username\Application Data\IBM\CTG\CICSTERM.INI
On Windows 2000 and Windows XP the location is typically as follows:
c:\Documents and Settings\username\Application Data\IBM\CTG\CICSTERM.INI
where username represents your Windows logon name.
172 CICS Transaction Gateway: Windows Administration

Terminal emulator preferences
If you share a computer with others, or are a user of multiple computers on a
network, your preferences will be used whenever and wherever you launch
terminal emulator. This functionality is provided by means of Windows
roaming user support.
The CICSTERM.INI file is not erased when you uninstall CICS Transaction
Gateway. Therefore, when you re-install CICS Transaction Gateway, the
settings from the old CICSTERM.INI files are used by the emulator.
The terminal emulator has a menu bar with File and Settings menus.
The commands on the File menu are:
Print Prints the emulator screen. This has the same effect as pressing the
Print Screen key.
Exit Stops the terminal emulator.
The commands on the Settings menu are:
Font Opens a standard Windows dialog box that allows you to
select any of the fixed-pitch fonts installed on your system.
Select a font, font style, and size, and then select OK. The
terminal window is then resized according to your font
selection.
Autosize Specifies that the size of TrueType fonts is adjusted according
to the size of the terminal window. That is, when you
maximize, minimize, or drag the borders to resize the
window, the font is resized to match the new window size.
This command has no effect if the current font is not a
TrueType font.
Save on Exit Specifies that the current font, terminal window size and
terminal position will be saved when you close the terminal
window. The settings are saved in the CICSTERM.INI file, as
explained at the start of this section.
The CICSPRNT command
The CICSPRNT command controls 3270 printer terminal emulation.
An application running on a server can direct output to a printer in one of
two ways:
1. An application running from a terminal can initiate printing by sending a
map or data with the PRINT indicator set
2. 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
Chapter 11. Terminal Emulation 173

The CICSPRNT command
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.
For CICSPRNT emulators, the maximum screen size is 27 rows by 132
columns. This is because the Client daemon supports the ASCII-7 subset of
the 3270 data stream architecture, which supports only 12 bit addressing. For
more information, see CICS Transaction Gateway: Programming Guide.
Note: 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.
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 -f
Wait for confirmation before completing -q
Inhibit all ouput messages -q
Issue one print job per transaction -j
You issue the CICSPRNT command once with all the parameters you require.
The following is an example of a CICSPRNT command:
CICSPRNT -s=CICSOS2 -n=P123 -t=XPRT -f=clprint.txt -q
In this example:
-s=CICSOS2 Specifies that a 3270 print terminal emulator is started for the
server CICSOS2.
-n=P123 Specifies that the 3270 print terminal emulator characteristics
are defined by the terminal definition P123 (in the terminal
control table for CICS for OS/2 in this case.)
-t=XPRT Specifies that the initial transaction is XPRT.
174 CICS Transaction Gateway: Windows Administration

-f=clprint.txt Specifies that the print file to which print requests are
appended is clprint.txt.
-q Specifies that the display of messages output by the command
is disabled.
All parameters of CICSPRNT are optional, except that you must specify either
-n=netname or -m=modelname. That is, you can enter the CICSPRNT command
with just the -n or the -m parameter, or both, and defaults for other
parameters are taken from the configuration file. Full details of the parameters
are given in “CICSPRNT command reference”.
If the system upon which the Client daemon is running 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.
The CICSPRNT process runs as a minimized window, and the window can be
enlarged to view the current status of the printer. You can use an action
available from a pulldown menu to terminate the print function.
CICSPRNT and user exits
You can use CICSPRNT to drive EPI user exits.
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 the commands:
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 169.
CICSPRNT command reference
For an explanation of syntax diagrams, see “Conventions and terminology
used in this book” on page x.
CICSPRNT Command Syntax
►► CICSPRNT
-s=servername -t=initialtransid -j
-s -t
-r=servername
-r
The CICSPRNT command
Chapter 11. Terminal Emulation 175
►

The CICSPRNT command
► -m=modelname
-n=netname -p=printcmd -q -?
-f=printfile -w
The options are:
-f=printfile
Specifies the name of a file to which the output of print requests is
appended. 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 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, then the command must
176 CICS Transaction Gateway: Windows Administration
-j
►◄

e 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 filename
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.
The CICSPRNT command
Chapter 11. Terminal Emulation 177

The CICSPRNT command
-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.
178 CICS Transaction Gateway: Windows Administration

|
|
|
|
Chapter 12. Workload Manager
This chapter discusses how to use the Workload Manager to improve
performance. It consists of the following:
“Workload Manager overview” Read this to learn what the Workload
Manager can do, and for an explanation
of key terms.
“What the Workload Manager needs to
know” on page 181
Read this to learn what information you
must supply to the Workload Manager.
“Load balancing algorithms” on page 183 Read this to learn about the two types of
load balancing that are available.
“Workload Manager failure recovery” on
page 184
“Workload Manager implementation” on
page 184
“Workload Manager installation” on
page 185
“Tracing the Workload Manager” on
page 186
“Workload Manager programming
requirements” on page 186
Read this to learn what the Workload
Manager does if a CICS region becomes
unavailable.
Read this if you are writing user exit
programs, and want to know how the
Workload Manager will interact with your
code.
Read this for information on installation.
Read this if you want to trace the
Workload Manager.
Read this for information on standards
applicable to programs that use the
Workload Manager.
For details of how to configure the Workload Manager see “Configuring the
Workload Manager” on page 84.
Workload Manager overview
The Workload Manager is designed to handle various problems when the
Client daemon is used to connect with one or more CICS servers (CICS
regions):
v How to get round the restriction on the number of clients that a single
CICS server can accommodate on a particular port.
v How to distribute work across available, equivalent CICS regions.
v How to favor one region over another (biasing).
v How to handle requests that fail to reach a target CICS region.
© Copyright IBM Corp. 1996, 2002 179

|
|
|
|
|
|
|
|
|
Workload Manager
The Workload Manager resolves these problems and others by dynamically
selecting target regions and ports based upon criteria that you configure.
Key concepts
It is essential to understand the following concepts:
Regions
A region is a physical instance of a CICS server, for example, TXSeries
for Windows NT or AIX. This includes the programs and resource
definitions for that region.
Programs
CICS programs are executable units that can be started within a CICS
region. A particular CICS program might be available on multiple
CICS regions. The Workload Manager has a list of CICS regions on
which the program is defined (program affinity).
TCP/IP address
An address that uniquely identifies a machine on a particular
network. Each machine may have many threads of execution running
simultaneously; a TCP/IP port uniquely identifies a particular thread
of execution.
TCP/IP port
A numeric TCP/IP end-point in the range of 0-65535. This port
number is defined in the configuration file (CTG.INI) file for each
instance of a server definition.
The number of client requests that can be handled on a particular port
varies with the CICS server platform. For example, a TXSeries for AIX
or TXSeries for Windows NT may handle client requests via a number
of ports, but only about 250 client requests can be handled per port.
You might need to define multiple server instances.
Server instance
An entry in CTG.INI that corresponds to an instance of a CICS server.
For a particular CICS region there may be multiple instances of CICS
server definitions, each with different port numbers. The names
provided by the Server name configuration setting (Server=servername
in the configuration file) are used in the actual ECI requests. In the
Workload Manager section of the configuration tool, the server
instances are gathered together in Server Groups.
In CICS Universal Client Version 3.0 this was known as a Listener.
Server Group
The configuration tool uses Server Groups to group together server
instances. A Server Group can correspond to one CICS region on a
server, or to several physical servers.
180 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
The first time an instance of the Client daemon makes a request, it
selects a server instance from the group at random. For the duration
of the life of that Client daemon instance, all subsequent requests to
that Server Group are sent to the same server instance.
An ECI program can be associated with a Server Group. The
Workload Manager assumes that the program exists on all server
instances in the Server Group.
Workload management
The ability of the Workload Manager to select a suitable CICS server
as a target for a client request. The load balancing algorithms try to
spread the workload over various server instances on a particular
region (via random selection) and they allow the user to effectively
specify a bias for the selection of a particular region. Known inactive
regions are not considered for selection.
Note: Apart from TCP/IP, other supported protocols can be used to
communicate with CICS servers. For example, SNA can be used, and in
this case the server instances can be identified by Logical Units (LU),
rather than by TCP/IP ports.
What the Workload Manager needs to know
This section discusses how CICS server instances relate to the CICS regions,
and the information required by the Workload Manager to perform its load
management.
The following table illustrates knowledge that the Workload Manager must
have. Specifically, the Client daemon must be able to correlate server instances
against the regions to which they belong.
CICS Region Server instance
REGION1 CICS1
CICS2
CICS3
REGION2 CICS4
CICS5
REGION3 CICS6
Workload Manager
The Client daemon can connect to a specific region through only one server
instance. So, in the example, a Client daemon can connect to a region using
one of the following groups of servers:
v CICS1, CICS2, CICS3
v CICS4, CICS5
Chapter 12. Workload Manager 181

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Workload Manager
v CICS6
For example, connections from a specific Client daemon to CICS2, CICS4, and
CICS6 are valid. Connections to CICS1, CICS3, and CICS5 are also valid, but
not desirable because CICS1 and CICS3 belong to the same region.
As mentioned previously, if a TCP/IP CICS region needs to service a large
number of clients, it might need to define multiple server instances, each with
its own port number. From a client perspective, each server definition
represents a uniquely targetable CICS region instance.
For example, if a port can handle 200 concurrent clients and there are 8000
clients, 40 ports are needed to support all clients. If the clients can distribute
their connections across these ports, this would optimally result in 200 clients
per port. Using a random distribution model, it is statistically possible for the
distribution to be 210 clients on one port and only 190 on another (assuming
200 on the remainder). This would result in a set of client failures. The
solution is to increase the number of ports available. For example, increasing
the number of ports to 50 would result in a randomly even distribution of 160
clients/ports. The random selection algorithm would now have to deviate by
25% to exceed 200 clients on one port.
As a port can handle only a relatively small number of concurrent client
connections, balancing the distribution of server instances across all the clients
is vital. In the example, if all clients selected CICS2 as the connection to
REGION1, it is likely that the port for CICS2 would quickly be overloaded,
resulting in failures. If all clients need to access REGION2, 50% should use
CICS4, and 50% should use CICS5.
Not all CICS programs need be available on all possible CICS regions. The
Workload Manager knows the name of the program that the client request is
for, and can select, from a subset of all regions, those regions on which a
particular program is defined. The Workload Manager also has knowledge of
a set of regions to which undefined programs may be routed.
For example:
Program Region Average Elapsed Time
PROG1 REGION1
REGION2
REGION3
PROG2 REGION1
REGION3
PROG3 REGION2 5
182 CICS Transaction Gateway: Windows Administration
10
20
15
20
10

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Workload Manager
This data can be used both to monitor application execution, and to provide
input to workload management algorithms.
To sum up, the Workload Manager must know:
v Which regions the Client daemon can connect to
v The server instances that belong to each region
v The programs that can run in each region
You supply this information using the configuration tool which produces the
appropriate entries in the configuration file; see “Configuring the Workload
Manager” on page 84.
Load balancing algorithms
You can select a round-robin algorithm or a biasing algorithm for load
balancing. You select an algorithm using the configuration tool; see
“Configuring the Workload Manager” on page 84.
The round-robin algorithm
The round-robin algorithm assumes that all CICS regions are equally valid for
selection. In the round-robin algorithm, when the Client daemon is initially
started, it reads from the configuration file a list of all possible CICS regions
to which any ECI request can be sent.
The Workload Manager also records the last region selected. When a new ECI
or EPI request is made, the next region in the list is selected as the target, and
the Workload Manager advances the next region indicator. When it reaches
the last region it loops around to the first one.
The biasing algorithm
The biasing algorithm provides a way of balancing workload by specifying
that workload distribution should favor particular regions. For example, if
there are two regions with a bias of 75 and 25, program requests are sent in a
ratio of 3:1 to the first region.
If a region fails, the internal biasing calculation changes. If two regions are
available, one with a bias of 100 and the other with a bias of 0, all requests
are sent to the first region. If the first region becomes unavailable, all requests
are directed to the second region. A bias value of 0 is a special case, meaning
use only if no other region is available.
Another way of looking at biasing is:
probability a region will be selected = bias for region
----------------total
bias for all regions
Chapter 12. Workload Manager 183

|
|
|
|
Workload Manager
The biasing algorithm works only for ECI calls. If you try to run an EPI
application whilst the biasing algorithm is selected, the round-robin algorithm
is used instead.
Workload Manager failure recovery
If a request to route an ECI call to a particular region fails, indicating that the
region is no longer available, the region is removed from the list of available
regions.
If a request fails to reach the target CICS region the Workload Manager tries
again, this time sending it to a different region that it knows is available. The
region that failed is removed from the list of active regions. It is added back
after a period of time which you specify in the Region timeout (s) field in the
configuration tool. If the region fails again, the process is repeated.
Workload Manager implementation
The Workload Manager is invoked during ECI and EPI calls from the Client
daemon, and implements ECI and EPI user exit functions. These ECI and EPI
exit functions are accessed during processing at a number of points during the
execution of a request. They are described in CICS Transaction Gateway:
Programming Guide.
The exit is implemented as a re-entrant multi-threaded Dynamic Load Library
(DLL). This exit (code) is dynamically loaded by each client application that
executes. The DLL executes in the process address space of the ECI-calling
application rather than the Client daemon.
ECI implementation
The Workload Manager is implemented as a Windows DLL called
cclmecix.dll. This DLL contains implementations for the following functions:
CICS_EciInitializeExit
Initialize the exit. Called once per process at the first ECI call. This
function builds the list of available regions and other attributes.
CICS_EciExternalCallExit1
Called at the start of an ECI call. This function is passed a reference to
the ECI parameter block and may change the value of the
eci_system_name field to select an alternate CICS server. The value of
this field may be a Server name. This function selects the correct
target CICS server for each ECI client request. This function involves
workload management algorithms.
CICS_EciSystemIdExit
If on return from the CICS_EciExternalCallExit1, the ECI request fails
to reach the target CICS server, either because of communication
184 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
Workload Manager
failure or a CICS server failure, CICS_EciSystemIdExit is called to
select an alternate CICS server target. The function flags that a CICS
server is no longer available and should be removed from the list of
selectable CICS servers. The workload management algorithm is then
re-executed to select the next CICS server to be targeted by the Client
daemon.
EPI implementation
The Workload Manager is implemented as a Windows DLL called
cclmepix.dll. This DLL contains implementations for the following functions:
CICS_EpiInitializeExit
Initialize the exit. Called once per process at the first EPI call. This
function builds the list of available regions and other attributes.
CICS_AddTerminalExit
Selects a CICS server.
CICS_EpiSystemIdExit
CICS_EpiSystemIdExit is called to select an alternate CICS server
target. The function flags that a CICS server is no longer available and
should be removed from the list of selectable CICS servers. The
workload management algorithm is then re-executed to select the next
CICS server to be targeted by the Client daemont.
Instead of using the supplied Workload Manager you can write your own
user exits that implement the ECI and EPI functions, and these exits can be
driven by the CICSTERM and CICSPRNT commands. Information on
producing such exits is given in the CICS Transaction Gateway: Programming
Guide book.
When the Workload Manager is activated for a CICSTERM/CICSPRNT
command, it determines which server the Client daemon should connect to.
The Workload Manager server selection overrides any server specified with
the CICSTERM or CICSPRNT command.
Workload Manager installation
When you install CICS Transaction Gateway, the ECI Exit DLL (cclmecix.dll)
and the EPI Exit DLL (cclmepix.dll) are installed into the \bin
subdirectory.
Once installed, the exit is used by succeeding ECI client calls without
modification to any currently existing ECI program.
The supplied load management DLLs can coexist with any user-written DLLs.
With the exception of CICS_EciSetProgramAliasExit, user-written DLLs are
called after the load management DLLs.
Chapter 12. Workload Manager 185

Workload Manager
Tracing the Workload Manager
You can enable tracing for the Workload Manager in two ways:
1. By selecting Workload Manager in the Trace section of the configuration
tool.
2. By specifying LMG on the CICSCLI -m command.
This command overrides the configuration setting.
By default, tracing of the Workload Manager is not enabled.
Workload Manager programming requirements
To invoke the Workload Manager correctly, the eci_version field in the
ECI_PARMS control block passed to the CICS_ExternalCall function must be
ECI_VERSION_1A or later.
The Workload Manager ensures that all calls in an extended Logical Unit of
Work (LUW) are routed to the same CICS server.
186 CICS Transaction Gateway: Windows Administration

Chapter 13. The Terminal Servlet program
This chapter describes how to use the Terminal Servlet to access CICS 3270
applications using a Web browser.
v “What is the CICS Transaction Gateway Terminal Servlet?” tells you what a
servlet is, and in particular what the CICS Transaction Gateway Terminal
Servlet does.
v “Installing and configuring the Terminal Servlet” on page 189 discusses how
you install and configure the Terminal Servlet.
v “Using the Terminal Servlet” on page 195 describes what you can do with
the Terminal Servlet, and how to invoke it from your Web pages.
v “Properties and parameters reference” on page 200 provides a complete
reference to the servlet properties you can specify for the Terminal Servlet.
v “Migrating from the CICS Internet Gateway” on page 245 describes what
you need to do to migrate from Windows running the CICS Internet
Gateway to using the Terminal Servlet.
v “CICS Transaction Server for z/OS Web Interface” on page 206 describes
how HTML templates generated for use by the CICS Web Interface can be
used by the Terminal Servlet.
It is advisable to read through all of this chapter before configuring and using
the Terminal Servlet.
What is the CICS Transaction Gateway Terminal Servlet?
Servlets are Java programs that run on a Web server machine, inside a
Java-enabled Web server or servlet engine, for example, WebSphere
Application Server (see Figure 22 on page 189). Java servlets have become
popular as alternatives to Common Gateway Interface (CGI) programs—the
Terminal Servlet is a replacement for the CICS Internet Gateway shipped with
IBM CICS Clients Version 2, which was a CGI program.
A servlet can be loaded automatically when the Web server is started, or
loaded when the first client request for the services of the servlet is made.
Unlike CGI programs, servlets are persistent, that is, once they are loaded
they stay running, waiting for additional client requests.
Being Java programs, servlets are portable across operating systems. And,
because the servlet interface is a standard, they can be used with different
Web servers on different platforms.
© Copyright IBM Corp. 1996, 2002 187

CICS Transaction Gateway Terminal Servlet
The Terminal Servlet allows you to access CICS 3270 applications using a Web
browser. You create Web pages that invoke the Terminal Servlet to start a
CICS transaction, display screen information sent from a CICS server, and
send screens back to CICS.
The Terminal Servlet can:
v Behave like a simple terminal emulator.
The CICS screen is displayed in the browser as part of an HTML form.
When you press one of the buttons in the form, the form is submitted and
data is sent to CICS.
v Substitute data from a CICS screen into HTML template files.
An HTML template file is used to determine how CICS data appears in the
browser. The Terminal Servlet replaces variables in the HTML template file
with CICS screen information, and the resulting output is sent to the
browser. For more information, see “Using variable substitution” on
page 198.
v Using server-side includes, incorporate variable information in a Web
page, or drive a terminal emulator without user interaction.
Server-side includes are statements in an HTML file (.shtml) that are
processed by the Web server before the Web page is returned to the
browser. For example, you can use a server-side include to invoke the
Terminal Servlet to display the value of fields in a CICS screen. For more
information, see “Invoking the servlet with a server-side include” on
page 197.
v Map CICS screens to Web pages.
Using the page mapping properties of the Terminal Servlet, you can
associate particular Web pages with particular CICS screens. For example,
you can specify the Web page to be displayed when the terminal is idle,
and no transaction is running. For more information, see “Page mapping
properties” on page 203.
Like EPI programming, the Terminal Servlet allows you to create new front
ends to existing CICS transactions. However, it also allows you to exploit the
power, flexibility, and platform-independence of Java programming.
Note: The Terminal Servlet does not support DBCS fields in 3270 data
streams.
188 CICS Transaction Gateway: Windows Administration

Workstation
Java-enabled browser
HTTP
Gateway server
Web server / servlet engine
Servlet
Gateway daemon
Client daemon
TCP62
CICS Transaction Server for OS/390
CICS server
Installing and configuring the Terminal Servlet
CICS Transaction Gateway Terminal Servlet
Figure 22. CICS Transaction Gateway using Terminal Servlet invoked by URL
This section discusses how to install the Terminal Servlet on the Web server
machine, and set the initialization parameters of the Terminal Servlet.
The procedure for installing and configuring the Terminal Servlet will vary
according to the Web server. However, you will need to do at least the
following:
v Configure the Web server’s CLASSPATH and PATH settings
v Add the Terminal Servlet to the Web server’s configuration
v Configure the servlet initialization parameters
v Consider other configuration options, such as security, logging, and
whether the Web server can process server-side includes.
Chapter 13. The Terminal Servlet program 189

CICS Transaction Gateway Terminal Servlet
Examples of installing and configuring the Terminal Servlet on a particular
Web server are available in the sample configuration documents. See “Sample
configuration documents” on page 266. The principles described should also
apply to other Web servers.
Refer to the documentation for your Web server for information on installing
and configuring servlets.
Configuring the Web server’s CLASSPATH and PATH settings
You must ensure that the two CICS Transaction Gateway jar files,
ctgclient.jar and ctgserver.jar, are in the Web server’s classpath.
If you do not make the correct classpath settings, you may get a message to
the effect that you cannot update the servlet, and that the class
com.ibm.ctg.servlet.TerminalServlet cannot be loaded.
You must also ensure that the \bin subdirectory is in the Web
server’s path.
Adding the Terminal Servlet to the Web server’s configuration
To add the Terminal Servlet to the Web server’s configuration, you must
provide a Servlet Name and associate this servlet instance with the Terminal
Servlet class, which is com.ibm.ctg.servlet.TerminalServlet.
You can configure more than one instance of the Terminal Servlet. Each of
them would have a different Servlet Name, but would refer to the same
Servlet Class. In fact, you must create a different Terminal Servlet instance for
each CICS server that you want to connect to. Each instance of the Terminal
Servlet may use different initialization parameters, and this can be useful
when configuring for different CICS servers.
Configuring the servlet initialization parameters
After adding the Terminal Servlet to the Web server’s configuration, you must
set up the initialization parameters for the Terminal Servlet.
The following sections give some insight into how the Terminal Servlet works,
which will help you in setting appropriate servlet initialization parameters.
The Terminal Servlet now supports signon capable terminals. For information
on the full set of initialization parameters available, including those to provide
this type of terminal, refer to “Properties and parameters reference” on
page 200.
190 CICS Transaction Gateway: Windows Administration

As a starting point consider setting some of the following parameters:
Table 9. Servlet initialization parameters
Parameter name Notes
servlet@propertyFile The servlet can load configuration information from a
properties file. A sample servlet.properties file is
supplied, in the
\samples\terminalservlet subdirectory.
To use a properties file, set this parameter to the full
path name of the properties file you want the Terminal
Servlet to load. If you specify a properties file then you
may want to use this file for all other servlet
parameters. In this case, servlet@propertyFile is the
only parameter that you need to set.
servlet@extendedLogging The servlet writes logging information, for example,
error messages, to the standard servlet log. Set this
property to true to write more information to the log
file. You may find this helpful when first configuring
the servlet, but it should be turned off once the servlet
is set up correctly.
pool@maxTerminals Set this property to the maximum allowable number of
connections to the CICS server. You should ensure that
the CICS server has sufficient free tasks to handle this
number of concurrent connections. You should also
ensure that the CICS Client Maximum requests
configuration setting is at least as large as this property.
pool@serverName Each instance of the Terminal Servlet can connect to
only one CICS server. This gives you more control of
resource usage and security. Set this property to the
name of the required CICS server, as defined by the
appropriate Server name setting in your configuration.
If this property is not set, the default CICS server is
used.
pool@gatewayUrl Set this property if you want the servlet to connect over
the network to the CICS Transaction Gateway.
Apart from the name of the property file, all the servlet properties can either
be loaded from a properties file or set as servlet initialization parameters.
Initialization parameters override properties file entries.
The servlet property names are not case sensitive.
CICS Transaction Gateway Terminal Servlet
Terminal pooling
The Terminal Servlet uses a pool of terminals, and the servlet configuration
properties allow you to control the behavior of the terminal pool. The default
Chapter 13. The Terminal Servlet program 191

CICS Transaction Gateway Terminal Servlet
behavior is that a new terminal is connected to CICS whenever a user requires
one, up to the pool@maxTerminals limit. When the user has finished with the
terminal, it is disconnected.
If the pool@minTerminals property is set, this number of terminals is
connected to CICS when the servlet starts, and up to that number may be
connected to CICS but not in use at any time. This allows new users to be
allocated a terminal immediately, without waiting for a connection.
Setting the pool@reusingTerminals property allows terminals to be reused,
that is, when a user session ends, the terminal may be allocated to a new user
instead of being disconnected. This property has no effect if
pool@minTerminals is 0. Any transaction running on the terminal is ended
and the screen is cleared, before it is reused. However, if a user has signed on
to CICS (using CESN for example), the terminal will still be signed on when it
is reused. For this reason, do not set this property unless you are sure it is
suitable for your environment.
The pool@idleTimeout property allows terminals that have been allocated to
a user to be released if they have not been used for the specified timeout
period. This property defaults to 0, that is, no timeout.
Using a display request with the values: pool@connectedTerminals,
pool@freeTerminals, and pool@terminalsInUse, you can query the number of
terminals that are connected, free, or in use for a particular instance of the
Terminal Servlet.
Page mappings
Page mappings tell the Terminal Servlet what Web page to display for a
particular CICS screen or terminal state.
The servlet’s choice of which page to display is based on the current page
mapping settings, the current screen handler class, and the state of the
terminal.
The Terminal Servlet first looks at the page mapping properties to see if there
is a specific page set for the current state of the session, as follows:
Session State Page Mapping Property
an error has occurred page@error
the terminal is idle - no transaction is
running
page@idle
the terminal has been disconnected page@disconnected
there is a screen handler for the current Page mapping for the class name of the
screen
screen handler
192 CICS Transaction Gateway: Windows Administration

If no specific page is found, the page identified by the page mapping property
page@default is used. If this is not set, an error message is displayed instead.
The value of a page mapping property can be set in two ways:
1. A URL, for example:
http://webserver/index.html
2. A template file to be loaded for variable substitution. This must start with
″file://″, for example:
file://d:/pages/template.html
CICS Transaction Gateway Terminal Servlet
If you set the servlet@templateDir property, template filenames can be
specified relative to the template directory.
Example settings for page mapping properties are as follows:
page@error=http://server/errors.html
page@idle=http://server/idle.html
page@disconnected=/ctglab/html/servlet/epissam.html
page@default=file://epissam1.html
To set a page mapping for a particular screen, you must create a Screen
Handler bean that can recognize that screen. Then, you must set the
pool@handlerPath property to ensure that the Screen Handler bean is loaded
by the Terminal Servlet. If, for example, you have created a Screen Handler
bean called MAP1ScreenHandler in a package called testmaps, then the page
mapping property for that screen handler is:
page@testmaps.MAP1ScreenHandler.
The name of the class is case sensitive. As for the standard page mappings,
you set the property to the name of the Web page to display, for example:
page@testmaps.MAP1ScreenHandler=http://server/test.html
A page mapping can also be set in a request parameter to the Terminal
Servlet, in which case it applies only to that request and overrides any page
mappings associated with the instance of the servlet being used. You can
query the current setting of a page mapping with an appropriate request (see
“Displayable properties” on page 205).
Screen Handler beans and terminal disconnection
For a terminal to be disconnected successfully, it must exit from running
transactions. The Terminal Servlet’s default behavior for achieving this is to
send the AID (Attention identifier) PF3 key to CICS. However, if you will be
running transactions for which this will not work, you should create one or
more Screen Handler beans that know how to exit the relevant screens.
Chapter 13. The Terminal Servlet program 193

CICS Transaction Gateway Terminal Servlet
You can generate Screen Handler beans automatically from BMS maps using
the BMS Map Conversion Utility (BMSMapConvert) supplied with the CICS
Transaction Gateway, or you can write your own classes. For information
about Screen handlers and how to create them, see the CICS Transaction
Gateway: Programming Guide book.
To load screen handlers into the servlet, set the pool@handlerPath property.
The handler path can include .jar files, .zip files and directories, although
sub-directories will not be searched. For example, in the servlet properties file
you might add:
pool@handlerPath=d:\handlers\handlers.jar;d:\handlers\test
to load screen handler classes from a .jar file and from a directory. See the
sample properties file for more information on setting this property.
You can also specify a default screen handler (using the property
pool@defaultHandler), which is used to exit from a screen if no other screen
handler recognizes it. The sample default screen handler is
com.ibm.ctg.epi.DefaultScreenHandler, which sends the AID PF3 to CICS.
Any screen handler bean that can be loaded from the classpath or from the
handler path can be used as the default screen handler.
The servlet will not keep trying to exit a running transaction indefinitely. The
property pool@exitRetryLimit controls how many attempts it makes to exit
the transaction. The default value of this property is 10, but you should
ensure it is large enough for your environment. If the servlet finds there is
still a transaction running on the terminal after this many attempts to exit, the
terminal is assumed to be ‘dead’ and it will not be disconnected or allocated
to a user. The only way to discard dead terminals is to unload the servlet,
stop and restart the CICS Transaction Gateway, and load the servlet again.
If you have configured the servlet properly and provided Screen handler
beans, you should not have any dead terminals.
Considering other configuration options
Other configuration options that you should consider are:
v Security
You may need to control access to the Terminal Servlet.
v Logging
The Terminal Servlet writes log information to the standard servlet log. You
can set logging on or off.
v Session tracking
You should configure the Terminal Servlet to use session tracking.
v Server-side includes
194 CICS Transaction Gateway: Windows Administration

You may wish to configure your Web server to process server-side includes.
Loading the Terminal Servlet
After you have configured the Terminal Servlet and saved the settings, you
must load it. You can choose whether to load it immediately, or each time
your Web server starts up.
Using the Terminal Servlet
If you have not configured the Terminal Servlet properly, error messages are
displayed when the Web server attempts to load the Terminal Servlet. For
more information refer to the Terminal Servlet section in the CICS Transaction
Gateway: Gateway Messages book.
This section describes how to use the Terminal Servlet. It describes the
different ways in which the Terminal Servlet can be invoked, and also how to
develop the Web pages that use the Terminal Servlet.
Sample files are provided in the \samples\terminalservlet
subdirectory. File samples.txt describes the samples.
Connecting to CICS and starting a transaction
An instance of the Terminal Servlet can only connect to one CICS server. For
each CICS server that you want to allow access to, you will have created an
instance of the servlet. You might also have created instances of the servlet
that have different initialization parameters.
To start a transaction on the CICS server, you must invoke the Terminal
Servlet with a suitable request.
Invoking the Terminal Servlet
There are three ways to invoke the Terminal Servlet:
v by URL
v with an HTML form
v with a server-side include.
CICS Transaction Gateway Terminal Servlet
In each case, you need to know the name of the servlet instance that you
want to use, and you pass the servlet one or more request parameters that tell
it what action to take. The parameter names and values are the same in all
cases, but the way you specify them is different.
To start a transaction on the CICS server, the parameters you must provide
are:
Chapter 13. The Terminal Servlet program 195

Using the Terminal Servlet
Parameter Name Parameter Value
request send
transaction the transaction ID of the transaction you want started.
Note however that ATI transactions cannot be started for the
Terminal Servlet.
The servlet will allocate a terminal to the user, if it is required.
The full set of request parameters are listed in “Request parameters” on
page 204.
Invoking the servlet by URL
To invoke a servlet instance called TerminalServlet, link to the URL:
http://your_webserver/servlet/TerminalServlet
where your_webserver is the hostname of your Web server and /servlet/ is the
location of your servlet engine (or the context for the servlet).
You can encode request parameters in the URL in the form of a query string,
for example:
http://your_webserver/servlet/TerminalServlet?request=send&transaction=CECI
You should use this method of invoking the servlet when you do not need the
user to enter any information.
Invoking the servlet with an HTML form
With this method, you create an HTML form in a Web page. For example:
(Tags to place text entry areas, buttons, and other prompts go here)
is a form that would invoke the servlet called TerminalServlet. The METHOD
can be GET or POST. The various elements of the form have names and
values, and these are sent to the servlet when the form is submitted. If you
know you want to set a particular request parameter, add it as a hidden item
in the form, for example: . Hidden inputs are always sent to the servlet. In general, the
name of a form element is the name of a request parameter, and its value is
the value of the request parameter.
This is the only way to send user-entered information to the servlet.
The supplied sample, epissam3.html, illustrates the HTML form method; see
the samples.txt file on the product CD.
196 CICS Transaction Gateway: Windows Administration

Invoking the servlet with a server-side include
A server-side include is processed by the Web server before the Web page is
sent to the user. The servlet is invoked, and any output it generates is
included in the Web page in place of the server-side include tags. The user
only sees the servlet output in the Web page.
In the HTML source, a WebSphere server-side include of the servlet looks like
this:
A server-side include can be used to add variable information to a Web page,
or to drive a terminal to perform some action whenever a Web page is
displayed, without any user involvement.
You can add as many server-side includes to a Web page as you wish, but
note:
v Server-side includes in one page may be processed in parallel. You can
therefore not be sure in which order they are performed, although usually
this is the order in which they occur in the source.
v The servlet stores session information that allows it to access the terminal
allocated to a user. If the user session is invoked by a server-side include,
subsequent server-side includes in the same page will not be able to access
the session information. Once the page has been sent to the user, the
session is established, and a page with multiple server-side includes will
work correctly.
The supplied sample
\samples\terminalservlet\epissam2.shtml illustrates the
server-side include method.
What happens next?
When the servlet has been invoked from a form or by linking to a URL, some
output must be sent back to the browser. To decide what should be displayed
to the user, the servlet uses the page mapping properties that you have set up,
see “Page mappings” on page 192.
Displaying screens and fields
There are two ways to include CICS screen information in a Web page:
v server-side includes
v variable substitution.
You can mix the two approaches if you want to.
Using the Terminal Servlet
Chapter 13. The Terminal Servlet program 197

Using the Terminal Servlet
Using server-side includes
Your Web server must be configured to process server-side includes. You
create SHTML pages that contain server-side includes that invoke the servlet.
The output from the servlet is inserted into the page in place of the
server-side include.
For example, to display the screen, as part of an HTML form, using
WebSphere:
or to display the contents of the 22nd field on the screen, using WebSphere:
Using variable substitution
You create HTML template files that the servlet will load. The servlet replaces
variables in the file with CICS screen information, and the resulting output is
sent to the browser. You use page mapping properties to tell the servlet what
template file to load (see “Page mappings” on page 192).
For example, a template file for the CESN signon screen might look like:
CICS Signon
CICS Signon
Userid:
Password:
where the variables are &USERID; and &PASSWORD;. You can identify fields
by number - to use names for fields, as in this example, you must have a
Screen Handler bean which can recognize the screen and set fields by name.
Page mapping property values can be the names of HTML template files or
any URL. So that the servlet knows that a page mapping property identifies
198 CICS Transaction Gateway: Windows Administration

an HTML template, you should set it to the value file://template_filename, for
example: file://d:/html/templates/test.html.
What can be displayed?
Any piece of information that can be displayed by a server-side include can
also be used for variable substitution, and vice-versa. The variable name used
in a template is the same as the value of the display parameter in the
server-side include.
Generally, you can display:
v The screen, as part of an HTML form
v A field - identified by number, or by name, if you have a Screen Handler
bean for it
v Servlet configuration settings
v The number of terminals that are currently connected, in use, and free.
The full set of properties that can be displayed is listed in “Properties and
parameters reference” on page 200.
Sending the screen back to CICS
To send the screen back to CICS you must invoke the servlet with the request
parameter set to ″send″. You do not need to provide a transaction parameter -
it is ignored if a transaction is already running. To update the screen with
new information before sending it back to CICS, you specify further request
parameters that identify the fields (by name or number) and what they should
be set to.
For example, the following WebSphere server-side include:
sets the fields named USERID and PASSWORD to the values given, and then
send the screen to CICS. In an HTML form, you might use the form element
. When the user
submits the form, the request parameter USERID is set to the value that they
entered.
Setting the AID
The default AID is Enter.
Using the Terminal Servlet
To set the AID from an HTML form, include a Submit button, specified like
this:
Chapter 13. The Terminal Servlet program 199

Using the Terminal Servlet
.
If the user presses the button, the servlet is sent the request parameter
″DFH_PF3″ with the value ″Exit″ (which the servlet ignores). The AID is set to
PF3. In a,WebSphere server-side include, you could set the AID like this:
The full set of request parameters is listed in see “Properties and parameters
reference”.
Disconnecting
When the servlet has allocated a terminal to a user, it is retained until:
v The servlet is invoked with the parameter ″request″ set to ″disconnect″
v The user’s session on the Web server expires
v If the pool@idleTimeout property has been set, the terminal is
automatically disconnected if it is not accessed for the specified period of
time.
v The CICS Client is stopped
v The connection to the CICS server is lost - or the server goes down
v The servlet is unloaded by the Web server.
You should try to explicitly release terminals when they are no longer
required.
Note that when a user has established a session with the servlet and been
allocated a terminal, any instance of the servlet to which the user has access
can continue the session. The same terminal is used until the user disconnects
or the session is ended for some other reason. The page mappings and other
properties used for any particular request are those set for the instance of the
servlet that is processing the request.
Properties that can be set as request parameters, for example, page mappings,
override the settings for the servlet, but usually only apply to the current
request, and do not affect requests by other users or subsequent requests by
the same user.
Properties and parameters reference
This section describes the Terminal Servlet properties
200 CICS Transaction Gateway: Windows Administration

Properties and parameters reference
Servlet configuration properties
In general, these properties can be specified either in a properties file or as
servlet initialization parameters when you configure the Web server. The
names are not case sensitive. Values given as servlet initialization parameters
override settings loaded from a properties file. Apart from the servlet@debug
and servlet@extendedLogging properties, these settings cannot be changed
while the servlet is running. However, using the request parameter display,
you can query the current settings of a property, see “Displayable properties”
on page 205.
servlet@debug
If set to true, turns tracing on for all instances of the servlet. You can
turn tracing on or off while the servlet is running, and output is
directed to standard output. Note that turning tracing on seriously
impacts performance!
servlet@extendedLogging
If set to true, turns extended logging on. Output is directed to the
servlet log.
servlet@propertyFile
The full path name of a properties file to load. This property can only
usefully be set as a servlet initialization parameter.
servlet@templateDir
The name of a directory from which HTML template files can be
loaded. Setting this property prevents users from viewing files that
are not in the template directory or its subdirectories. If you do not set
this property, the servlet can load any file on the Web server that it
has access to.
pool@defaultHandler
The screen handler to use to exit screens when no specific handler is
found. If you set this to be one of the Screen Handlers loaded from
the Screen Handler path, make sure that the handler path is set before
the default handler.
pool@deviceType
The terminal model definition to use. If this property is not set, the
default is used.
pool@encoding
Allows you to specify the Java Encoding to be used. Refer to
″Appendix A. Java encodings″ in the CICS Transaction Gateway:
Programming Reference book for further details on this.
pool@exitRetryLimit
The number of times that the servlet will try to exit a running
transaction during terminal disconnection. This prevents the servlet
looping, if a screen cannot be exited.
Chapter 13. The Terminal Servlet program 201

Properties and parameters reference
pool@gatewayUrl
The URL of the CICS Transaction Gateway that the servlet should
connect to. The default is to use a local Gateway, that is local://.
pool@handlerPath
The path from which Screen Handler beans are loaded. You can
include directories, .jar files, and .zip files, but subdirectories are not
searched.
pool@idleTimeout
The maximum time in seconds to allow a terminal to be left idle
before it is automatically disconnected. The default value is 0,
meaning no timeout.
pool@installTimeout
The maximum time in seconds to allow a terminal to install before
failing. The valid range is 0 to 3600. The default value is 0, meaning
no timeout
pool@maxTerminals
The maximum number of terminals that can be connected to CICS
concurrently. The default value is 5.
pool@minTerminals
The number of terminals that should be kept connected to CICS when
not in use. The default value is 0.
pool@password
Specifies the password to be associated with a signon incapable
terminal at the time of creation.
pool@readTimeout
The maximum time in seconds to allow for conversational
transactions before timing out.. Valid range is 0 to 3600. A value of 0
meaning no timeout.
pool@reusingTerminals
If set to true, released terminals are kept connected for the next user.
The default behavior is to disconnect terminals when a user session
ends. You must also set pool@minTerminals for this property to have
any effect.
pool@serverName
The name of the CICS server to connect to. If this property is not set,
the default CICS server, as defined in your configuration is used.
pool@signonCapability
Specifies signon capability for extended terminals. Valid entries are
EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE.
202 CICS Transaction Gateway: Windows Administration

Properties and parameters reference
pool@pool@userid
Specifies the userid to be associated with a signon incapable terminal
at the time of creation.
screen@coloring
If set to true, colored fields are displayed in the color indicated in the
3270 datastream.
Due to the limitations of HTML, unprotected fields cannot be colored
and always appear as black text on a white background.
If the property is not specified. the Terminal Servlet displays the
screen with black text on a white background.
screen@cursoring
If set to true, JavaScript sets the screen cursor position. The default
setting is false.
screen@NeutralColor
Specifies the HTML color to which the screen handler will translate
the neutral 3270 color.
screen@stripBlanks
If set to true, the Web Browser formats the field text.
screen@stripEmptyRows
If set to true, the screen handler removes screen rows that do not
contain data.
screen@TrimFields
If set to true, the screen handler removes excess white space from the
start and end of any input fields.
Page mapping properties
Page mappings associate Web pages with particular screens or terminal states.
Page mappings can be specified in a properties file, or as servlet initialization
parameters, when you configure the Web server. However, using the request
parameter display, you can query the current settings of a page mapping, see
“Displayable properties” on page 205.
Standard page mapping properties Value
page@disconnected The page to show when the terminal is
disconnected.
page@error The page to show when an error occurs
page@idle The page to show when the terminal is
idle, that is, no transaction is running
page@default The page if no other page is specified.
page@screen The page to show for this screen.
Chapter 13. The Terminal Servlet program 203

Properties and parameters reference
Request parameters
These parameters are set only when a request is made. You can also specify
any other property that can be set on a request, for example:
servlet@extendedLogging.
Parameter name Parameter value
request Set to ″send″ to send a screen to CICS or ″disconnect″ to
end a session
If required, a new terminal session is started.
display The name of a property that can be displayed, see
“Displayable properties” on page 205.
translateText Set to ″true″ to translate the characters and & to
< > and & respectively. This is used when
text is displayed.
transaction The transaction ID of a transaction to be started. This is
only used if the request is ″send″ and the terminal state
is idle.
ATI transactions cannot be started for the Terminal
Servlet.
transactionData Additional parameters to pass to a transaction. This is
only used if the request is ″send″ and the terminal state
is idle, and a transaction was specified.
DFH_CURSOR The field where the screen cursor should be placed, as a
field index (a number), or the name of the field, if a
screen handler bean is available for the current screen.
DFH_ENTER,
DFH_CLEAR, DFH_PA1 -
3, DFH_PF1 - 24
This parameter name must be in upper case.
The value is ignored.
Use one of these parameters to specify the AID key to
be sent to CICS. This must be in upper case.
A field index The text to be set in the field.
Use to set the contents of a field when you know the
field index.
usingSession Set to false if no terminal session is required.
204 CICS Transaction Gateway: Windows Administration
If this parameter is set, any terminal used for this
request is discarded after use.

Parameter name Parameter value
matchOnIdle Set to false by default.
Properties and parameters reference
Normally the servlet only attempts to find a
ScreenHandler for the current screen when the terminal
state is ‘client’, that is, a conversational or
pseudo-conversational transaction is expecting a
response. Setting this property to true causes the servlet
to check the current ScreenHandler every time the
screen changes regardless of the state. You may want to
do this if you have transactions that use BMS maps, but
which are not conversational or pseudo-conversational.
If you have a large number of ScreenHandlers, the
servlet may run more slowly when this property is set
to true. For this reason, the default value is false.
In addition, if a Screen Handler bean is available for the current screen, you
can set any properties on that bean by specifying them in the request. For
beans generated by BMSMapConvert, the field names defined in the BMS
map are properties that can be set to the required text in the field.
Displayable properties
The following table shows the values that can be specified for the ″display″
request parameter or used for variable substitution, see “Using variable
substitution” on page 198.
Display values Displays
none Nothing. Use to suppress output from a
server-side include.
screen The screen - as part of an HTML form.
errorMessage If an error has occurred, the error
message.
errorCause If an error has occurred, further
information about the error.
DFH_CURSOR The name of the field where the cursor is,
if it can be determined, otherwise the
field index.
a field index The field text
a screen handler property name The value of the property if it can be
determined.
any of the servlet configuration properties The value of the property for the current
listed above
servlet instance.
Chapter 13. The Terminal Servlet program 205

Properties and parameters reference
Display values Displays
any page mapping property The value of the property for the current
servlet instance.
any request parameter, except for
″request″ and ″display″
The value of the property for the current
request.
pool@connectedTerminals The current number of connected
terminals, for this servlet instance.
pool@freeTerminals The current number of connected
terminals that are not in use, for this
servlet instance.
pool@terminalsInUse The current number of terminals allocated
to users, for this servlet instance.
CICS Transaction Server for z/OS Web Interface
The CICS Web Interface, included in CICS Transaction Server for z/OS
Version 1.2 and above, is a collection of transactions and programs supporting
direct access to CICS transaction processing services from Web browsers.
If you have generated HTML templates for use by the CICS Web Interface,
they can also be used as HTML templates by the Terminal Servlet. You will
have to make some changes to invoke the servlet instead of the CICS Web
Interface, but the format is basically the same.
To use the template file:
1. Copy the template file to a directory on the Web server.
2. Edit it to change the action to /servlet/TerminalServlet and add
a hidden element with name ″request″ and the value ″send″.
3. Generate a Map class and Screen Handler bean for the BMS map that the
HTML template refers to.
4. Compile the generated Java source files.
5. Copy the compiled class files to a suitable directory on the Web server.
6. Set the servlet property pool@handlerPath so that it will load the new
classes.
7. Set a page mapping property to associate the new Screen Handler bean
with the HTML template file.
206 CICS Transaction Gateway: Windows Administration

Chapter 14. Problem determination and problem solving
Preliminary checks
Most problems in a CICS Transaction Gateway system are caused by one of
the following:
v User errors
v Programming errors
v Configuration errors.
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?
See “Configure your programming environment” on page 53 for
information on setting CLASSPATH.
The CLASSPATH is displayed at the top of the CICS Transaction Gateway
trace output. See “Starting the Gateway with user-specified options” on
page 142 for information on starting the Gateway daemon with tracing
enabled.
v Is the environment configured correctly?
Refer to the documents listed under “Sample configuration documents” on
page 266.
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 you
specified in servername.
v Are there any messages explaining the failure?
See “Messages” on page 208.
v Are there any Java exceptions?
See “Java exceptions” on page 216.
v Does the problem occur only at certain times?
© Copyright IBM Corp. 1996, 2002 207

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Problem determination
This might be because the system is heavily loaded at those times; See
“java.lang.OutOfMemory exception” on page 217 for more information.
v Can you re-create the failure?
What to do next
If you think the problem is with the CICS Transaction Gateway, see
“Diagnosing common problems: Gateway daemon” on page 212, or
“Diagnosing common problems: Client daemon” on page 227 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 236 for information on how to contact IBM.
See “Documenting problems” on page 237 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 with the Gateway daemon
Messages
The Gateway daemon writes log messages to standard output (stdout) orto
standard error (stderr). If Gateway daemon tracing is enabled, it also writes
log messages to the trace output file.
Messages have the format:
CCLnnnnt:
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,
regardless of their type, you can use a command like the following:
ctgstart 1>&
Refer to the documentation for your operating system for more information
on redirecting output.
See CICS Transaction Gateway: Gateway Messages for an explanation of all CICS
Transaction Gateway messages.
208 CICS Transaction Gateway: Windows Administration

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 23.
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.
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 23. 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“Application tracing”
on page 210 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:
Problems with the Gateway daemon
Chapter 14. Problem determination and problem solving 209

Problems with the Gateway daemon
ctgstart -x
If you used the configuration tool to configure CICS Transaction Gateway, the
default destination for trace output is the ctg.trc file in the
\bin subdirectory. 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.
If the Gateway daemon is running as a Windows service: Either:
v Configure the Gateway daemon to enable tracing whenever it is started. See
“Using the configuration tool” on page 54.
v Use the -A option on the ctgservice command to pass tracing options to the
ctgstart command. See “Running CICS Transaction Gateway as a Windows
service” on page 146.
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.
For more information on starting the Gateway daemon with trace options, see
“Starting the Gateway” on page 141.
For more information on performance considerations, see Chapter 8,
“Performance” on page 135.
Application tracing
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 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.
When using Internet Explorer, the stderr data stream is written to the Java
console. To enable the Java console, in Internet Explorer version 5, you select
210 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tools —> Internet Options —> Advanced, then check the box next to Java
console enabled. You can then view the console by selecting View —> Java
Console.
JNI tracing
You cannot enable JNI trace through the configuration tool. Use one of the
following methods to enable it:
v When you start the CICS Transaction Gateway, issue the command
ctgstart -j-Dgateway.T.setJNITFile=filename
Problems with the Gateway daemon
where filename is the name of the file to which trace output is to be sent.
v While the CICS Transaction Gateway is running, use the system
administration functions. You must have enabled the TCPAdmin protocol
handler (see “TCPAdmin protocol settings” on page 69). See “Administering
your system” on page 149 for details of how to enable JNI trace
dynamically.
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
Using the CTG_JNI_TRACE environment variable to enable JNI trace is
supported only for migration purposes.
J2EE Tracing
Refer to “Tracing” on page 95 for information on using the tracing function
provided with the ECI and EPI resource adapters.
Servlet tracing and logging in WebSphere
IBM WebSphere Application Server provides the Advanced Administrative
Console to simplify the tasks associated with managing applications.
To enable servlet tracing in WebSphere do the following:
1. Configure WebSphere to send standard output and standard error to a file
of your choice:
In the Administrative Console, select the application server in which you
want to enable tracing. Under the General tab there are text-entry boxes
labelled Standard output and Standard error. You can type filenames in
these boxes to override the default destinations.
2. Enable tracing in the application:
Chapter 14. Problem determination and problem solving 211

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Problems with the Gateway daemon
v For the CICS Transaction Gateway Terminal Servlet, use the
servlet@debug property to enable tracing.
For more information see “Properties and parameters reference” on
page 200.
v For user-written applications, use Java directives to enable tracing. You
can type these in the Command line arguments box in the
Administrative Console. Use the same format for Java directives as in a
java command line call. For example, to enable full debug tracing, type
-Dgateway.T=on as the first command line argument.
See ″Tracing in Java client programs″ in the CICS Transaction Gateway:
Programming Guide book for further information on Java directives for
tracing.
3. Click on the Apply button, to update the WebSphere settings, and run the
servlet.
When a servlet runs, WebSphere writes logging information to the same
destination as standard output. This information includes start times, stop
times, and any error messages. For the CICS Transaction Gateway Terminal
Servlet, use the servlet@extendedLogging property to enable extended
logging. If you enabled extended logging, the Terminal Servlet writes to the
log every time it receives a request. This can provide useful information for
diagnosing problems but it reduces performance.
You can enable both tracing, and extended logging, while the Terminal Servlet
is running. For more information on Terminal Servlet properties see
“Properties and parameters reference” on page 200.
Diagnosing common problems: Gateway daemon
Problems running the configuration tool
Task Guide loses focus
Under some JVMs on the Windows and UNIX operating systems, you
might have problems when entering the name for a new server in the
Task Guide. If the text box loses focus after each key press, click the Next
button to move onto the next panel and then click the Back button to
return. You should now be able to input text normally. This is a JVM
problem.
Chinese, Japanese or Korean characters do not display correctly
To display Chinese, Japanese or Korean characters correctly on the
Windows operating system, set the system locale to Chinese, Japanese or
Korean. If characters still do not display correctly, install the relevant
world type font package. You can download world type font packages
from the following site:
212 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems: Gateway daemon
http://www.ibm.com/developerworks/java/jdk/linux130/
The Gateway daemon fails to find Turkish configuration settings
When you run the configuration tool under a Turkish locale for the first
time, by default the configuration settings are saved in file CTG.INI.ini.
Rename the file to CTG.INI to allow the Gateway daemon to find the
settings automatically. You only have to do this once, when the
configuration tool is first run.
The configuration tool fails to launch under Turkish and the Solaris 1.3.0
JVM
This is a known problem with the Solaris 1.3.0 JVM and has been raised
under SunBugs 4380798 and 4346718. A workaround is detailed under
SunBug 4380798 in the Sun Java Bug Database; to access this, go to
http://java.sun.com/, follow the link to Online Support and search the
Bug Database for 4380798.
Problems running the configuration tool in Turkish under the HP-UX JREs
Running the tool under HP-UX JRE 1.3 results in messages saying that
fonts are not found. Despite this, Turkish characters display correctly.
Codepage problems
A Gateway daemon trace shows the codepage in which the JVM is running. It
is displayed in the System Properties section at the top of the trace. Refer to
Appendix A, “Data conversion between the Client daemon and a CICS
server” on page 251 for information on finding the codepage 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 209
for information on tracing the Gateway daemon and the application. See
“Tracing” on page 219 for information on tracing the Client daemon, and
“Diagnosing common problems: Client daemon” on page 227 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 232, for information on
what to do if the Client daemon is not responding.
Problems when the Gateway daemon is running as a Windows service
If the Gateway daemon does not start, or clients cannot connect to it, when it
is running as a Windows service, it may be because input from the console is
enabled. Entries like those in Figure 24 on page 214 indicate that the Gateway
daemon is trying to read from the console:
Chapter 14. Problem determination and problem solving 213

Diagnosing common problems: Gateway daemon
11:37:58:472 : main: S-C: -> [ServerMessages: getKeys] ()
11:37:58:472 : main: S-C:

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You specify the name of the server KeyRing class in the KeyRing classname
field in the SSL protocol settings panel in the configuration tool. Do not
include the directory or file extension when you specify the KeyRing class
name. The CLASSPATH should include an entry for the directory that
contains the KeyRing class.
In a user application: The API call
SslJavaGateway.setKeyRing("ClientKeyRingName", "thePassword"); fails with
the following error in a user application:
java.lang.NoClassDefFoundError: com/ibm/sslight/SSLightKeyRing
Check that the CLASSPATH variable includes an entry for file cfwk.zip. This
file is supplied with the CICS Transaction Gateway.
JSSE:
Diagnosing common problems: Gateway daemon
JSSE assumed when using SSLight: If you pass a KeyRing or Keystore name to
CICS Transaction Gateway, but the class does not load, or cannot be found,
the Gateway daemon assumes that you are using JSSE and not SSLight.
iKeyMan locks with ″class not found″ exception: A message like the following is
received by the application:
java.lang.NoClassDefFoundError: com/ibm/security/pkcsutil/PKCSException
This happens if the IBM Java Cryptography Extension (JCE) package is not
installed. Ensure that you have installed the JCE supplied with CICS
Transaction Gateway in the ibm-jce.zip file. See “Installation” on page 114.
Application receives an ″access denied″ exception: A message like the following is
received by the application:
java.io.IOException: CCL6651E: Unable to connect to the Gateway.
[address = killerb2b, port = 8050]
[java.security.AccessControlException: access denied
(java.io.FilePermission f:/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, inCICS Transaction Gateway: Programming Guide, for more
information.
KeyStore name not recognized: Java interprets the back slash (\) character as a
parameter delimitter. If you used the back slash character as a directory
separator when entering the path name of the KeyStore file during
configuration, Java cannot recognize the name. 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 14. Problem determination and problem solving 215

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems: Gateway daemon
c:/mykeys/jsse/keystore.jks
c:\\mykeys\\jsse\\keystore.jks
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
occured. See “Tracing” on page 209 for more information on tracing.
ConnectFailed exceptions when running under load: Workstation versions
of Windows restrict the number of open requests that can be queued against a
socket. This might lead to intermittent Java ConnectFailed exceptions when
running under load. This is especially likely when using HTTP, because this
protocol opens and closes sockets frequently.
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:
CCL6664E: Unable to load relevant class to support the tcp protocol
216 CICS Transaction Gateway: Windows Administration

Diagnosing common problems: Gateway daemon
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″, inCICS 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.
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.
Too many threads: You can estimate the amount of virtual memory that is
required by the JVM as follows. Add together:
v the number of Connection Manager threads
v the number of Worker threads
v the number of background threads in use by Java
v the number of different network protocols in use
Then multiply this total by the size of the Java stack allocated to each thread
by the JVM.
In this calculation, assume that the number of active Java background threads
is about five. Refer to your Java documentation for a more accurate value. You
set the maximum numbers of Connection Manager threads and Worker
Chapter 14. Problem determination and problem solving 217

|
|
|
Diagnosing common problems: Gateway daemon
threads when you configure CICS Transaction Gateway. See “General
Gateway settings” on page 59 for more information.
The way that Java allocates memory depends on your JVM implementation.
Most JVMs allow you to control memory allocation by setting limits on the
sizes of the Java stack and the Java heap.
For more information on thread limits see Table 3 on page 17. For more
information on Java memory allocation refer to CICS Transaction Gateway:
Programming Guide and to your Java documentation.
Using Java debugging tools to debug user applications
The IBM Java SDK 1.3 for Windows NT includes file readme.devkit.ibm.html,
which is installed in the \docs subdirectory. This file describes
some of the debugging tools, such as jdb which are supplied with Java. These
tools can be useful for debugging application programs.
Programs using beans included in earlier versions of CICS Transaction
Gateway
See “EPI beans provided in earlier versions of the CICS Transaction Gateway”
on page 248 for information on beans that are now provided only as sample
programs.
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: Gateway Messages book explains all of these
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 error log (which has a default name of CICSCLI.LOG) is an ASCII text file
that you can browse using a standard text editor.
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.
218 CICS Transaction Gateway: Windows Administration

Problems with the Client daemon
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.
Pop-up messages
Errors generated from within the Client daemon are displayed in a pop-up
window. You must click on OK in the pop-up window before the Client
daemon can continue processing. There may be times when you do not want
messages to appear in pop-up windows, for example, if you leave the Client
daemon running unattended overnight. To disable the display of pop-up
messages, enter the following command:
CICSCLI -n
When the display of pop-up messages is disabled, the messages are still
written to the Client daemon error log. To re-enable the display of pop-up
messages, enter the following command.
CICSCLI -e
You can specify the -n parameter together with the -s parameter. The display
of pop-up messages is enabled by default.
Tracing
The Client daemon tracing is a very 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 you 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.
You can specify which components of the Client daemon you want to trace.
You control this with the CICSCLI -m command, (see “CICSCLI command
reference” on page 160), or by specifying a list of components using the
configuration tool.
The output from the trace function is a binary trace file called, by default,
CICSCLI.BIN in the \bin subdirectory. You can specify a
different name for this file, using the configuration tool. However, you cannot
change the .BIN extension. Using the Maximum Client wrap size
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.
Chapter 14. Problem determination and problem solving 219

Problems with the Client daemon
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.
See “Formatting the binary trace file” on page 222 for information on the trace
conversion utility.
Starting and stopping Client daemon tracing
To start Client daemon tracing, enter the CICSCLI command with the -d
option, for example:
CICSCLI -d=nnn
where nnn is optional, and is the maximum size in bytes of the data areas to
be traced. (The default value is 512.)
Note: It is recommended that you set at least -d=1000 to ensure that all
relevant data is included in the trace before sending it to your support
organization.
If you need to trace the Client daemon immediately from startup, you can
specify the -s and -d parameters together in the same CICSCLI command. For
example, the following command starts the connection to a CICS server with
the name CICSTCP, enables the trace function, and sets the maximum data
area size to be traced to 128 bytes:
CICSCLI -s=CICSTCP -d=128
You can specify which components are to be traced when you start tracing.
See “CICSCLI command reference” on page 160 for details.
To stop Client daemon tracing, enter the CICSCLI command with the -o
option, for example:
CICSCLI -o
220 CICS Transaction Gateway: Windows Administration

Problems with the Client daemon
The trace is also automatically stopped if you stop the Client daemon by
using the CICSCLI -x command.
Choosing which components to trace
ALL This option traces everything. It is the
preferred option; use it if performance allows,
and consider using the binary formatting tool
to filter information. See “Formatting the
binary trace file” on page 222 for details.
API.1 and API.2 These trace the boundary between the user
application or Java classes, and the Client
daemon. Switching on API.2 automatically
switches on API.1 as well.
DRV.1 and DRV.2 The protocol drivers trace the boundary
between the Client daemon and the network
protocol. Specify the DRV.1 and API
components if you are not sure whether a
problem is inside the Client daemon, and you
want to minimize the impact on performance,
for example when trying to determine a
performance problem.
You can also specify these components to help
to determine which product is causing the
system to lock up.
CCL This component traces the main Client
daemon process. Specify the API and CCL
components if you believe that the problem is
within the Client daemon.
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.
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. You turn on wrapping of trace using the Maximum
Client wrap size configuration setting, where you specify the maximum size
of the wrapping trace (in kilobytes). If this value is 0 (the default), wrapping
trace is not turned on.
Chapter 14. Problem determination and problem solving 221

Problems with the Client daemon
When wrapping trace is turned on, two files (called CICSCLI.BIN and
CICSCLI.WRP) are used. Each file can be up to half the size of the Maximum
Client wrap size value.
Formatting the binary trace file
You use the Binary Trace Formatter utility CICSFTRC to convert the binary trace
file CICSCLI.TRC 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. 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 binary trace files to format and then
concatenate (that is, the binary files were created with a wrapping trace).
If no filename 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.
-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 driven from a
text file (CCLSUMTR.TXT) which is read in at initialization time. This
defines the set of trace points for which you want summary tracing, and
the type of trace point. As DetailFormat reaches each trace point, if it is
one of the ones read in from this file, a line is generated in the summary
file. Use as requested by your IBM support organization; see “Program
support” on page 236.
The formatter can produce a summary of API calls that the user program
makes, and show the progress of the calls through the Client daemon. Specify
the API.2 component to produce a summary trace. Figure 26 on page 223
222 CICS Transaction Gateway: Windows Administration

shows an example. (The layout of your trace may be different, depending on
the contents of CCLSUMTR.TXT.)
-->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 SKNIGHTS) send data: Length=89
[000000bf,0000017c] 12:08:32.330 [7391] CCL1040 using slot = Slotp->Ctrl.ConvId = 6
[000000bf,0000017c] 12:08:32.350 [7099] CCL1037 Sync ECI call, so waiting for a reply...
[00000089,00000063] 12:08:32.400 ▌[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,000000a4] 12:08:32.551 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,00000168] 12:08:32.581

Problems with the Client daemon
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 SKNIGHTS |
+----------------------------------------------------------------------------------+
12345678901234567890123456789012345678901234567890123456789012345678901234567890
1 2 3 4 5 6 7 8
Figure 27. Screen capture from a formatted trace file
224 CICS Transaction Gateway: Windows Administration

|
|
|
Problems with the Client daemon
The formatter lists the commands which built the screen, and shows an
approximation of the screen.
In Version 5.0 of CICS Transaction Gateway, the Binary Trace Formatter utility
has been enhanced to format SNA and MPTN data structures within TCP62
data flows.
Client daemon trace analysis
The Client daemon trace file records detailed information on all actions taken
during the execution of a particular activity. You can use this information in
your problem determination activities, and to help understand how the Client
daemon performs a particular function, for example, establishing a connection
to a CICS server.
If you cannot interpret the trace yourself, you should contact your IBM
support organization and forward the unformatted binary trace file.
Some sample traces are shown in “Sample Client daemon trace” on page 226.
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.
[number]
A number to aid 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. These trace messages are explained in
CICS Transaction Gateway: Gateway Messages.
data
Some trace entries include a dump of key data blocks in addition to the
trace message.
Chapter 14. Problem determination and problem solving 225

Problems with the Client daemon
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 -d
CICSCLI -o
The trace was generated for an AIX Client daemon but is applicable to other
Client daemons.
17:03:57.580 [0000080c,00000908] [1007] TRC:▌CCL1042▐ *** CICS Client for AIX v5.0 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=’* ’, Codepage=819
...
...
...
17:04:00.625 [0000080c,00000908] [3102] CCL:▌CCL3114▐ CCIN install response: ApplId=’@0Z8AAAA’, Codepage=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. The trace file is overwritten each time a
trace is started. You can delete the file when required. Check
the date and 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 “Starting and stopping
Client daemon tracing” on page 220).
CCL3251 The client sends a CCIN transaction to the server to install its
connection definition on the server.
CCL3238 Reply to message CCL3238, includes the conversation ID for
this conversation.
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
226 CICS Transaction Gateway: Windows Administration

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 is the response to message CCL3114 with 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 CTG.INI 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 v5.0 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:CCL3429 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
Problems with the Client daemon
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” on page 228
v “TCP/IP communication problems” on page 228
v “APPC communication problems” on page 229.
v “TCP62 communication problems” on page 230
v “Traps” on page 230
v “The Client daemon stops responding” on page 232
This section lists problems for all supported operating systems, to provide for
cases where client and server are on different operating systems.
For information on error messages, refer to CICS Transaction Gateway: Gateway
Messages.
Chapter 14. Problem determination and problem solving 227

Diagnosing common problems: Client daemon
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
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
CTG.INI 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 signon capable?
CICSTERM attempts to install a signon capable terminal by default. If the
-a option works, the server probably does not support signon capable
terminals.
CICS servers require APAR fixes to support terminal signon capability; see
“Supported software” on page 22. 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 239 for general information about APARs.
TCP/IP communication problems
The following are solutions to problems that can occur when communicating
over TCP/IP:
A Client daemon running on Windows cannot load the TCP/IP protocol
driver
You have probably received message CCL3229E in a pop-up window and
message CCL3247 in the CICSCLI.LOG error log file. These messages indicate
228 CICS Transaction Gateway: Windows Administration

you have probably specified the wrong device driver in the configuration file.
For all TCP/IP communication, the Client daemon on Windows should use
the CCLWNTIP driver. Any vendor offering a WINSOCK interface can use
this TCP/IP driver.
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.
APPC communication problems
The following are solutions to problems that can occur when communicating
over APPC:
CCIN not recognized, CTIN not recognized
Diagnosing common problems: Client daemon
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 emulation. For information on which CICS servers support
EPI and hence CICS 3270 emulation, see Table 5 on page 27. 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 5 on page 27.
Automatic transaction initiation against a Client daemon terminal
does not work
Different products provide different APPC implementations for handling
inbound attaches. Therefore for the Client daemon using IBM eNetwork
Communications Server, Microsoft SNA Server, and IBM eNetwork Personal
Communications, you must predefine the CRSR attach program to relay the
information to the Client daemon. This is necessary to enable the CICS server
to perform automatic transaction initiation (ATI) against the Client daemon
terminals. (As long as the CICS server supports CICS 3270 terminal
emulation, see Table 5 on page 27.)
Chapter 14. Problem determination and problem solving 229

|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems: Client daemon
For the Client daemon therefore, you must define the inbound attach
transaction CRSR as follows:
A Client daemon running on Windows and using IBM eNetwork
Communications Server
Define CRSR to use program CCLCLNT.EXE. See “IBM
eNetwork Communications Server” on page 46.
A Client daemon running on Windows and using IBM eNetwork Personal
Communications
Define CRSR to use program CCLCLNT.EXE. See “IBM
eNetwork Personal Communications” on page 48.
SNA error log: The SNA error log can help your support organization to
diagnose problems. The path to the file, if the product is installed to its
default location, is as follows: c:\program files\Personal
Communications\pcwmsg.mlg
TCP62 communication problems
CCL5820 TCP62: Attempt to open server ’server1’ which is a
duplicate of ’server2’
Multiple server definitions with identical combinations of Local LU, Partner
LU, and Mode name are not permitted in CTG.INI in the CICS Transaction
Gateway Version 5.0. 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. Existing Client applications that use different server
names to send requests to the same CICS region continue to work if a user
exit is defined to redirect requests. A sample user exit that does this is
provided; see \samples\samples.txt.
Traps
Dr. Watson
On Windows systems, the Dr. Watson tool can supply useful information
in the event of an operating system trap. It attempts to produce a stack of
trace exceptions. Dr. Watson is the program error debugger supplied with
Windows. Refer to the product documentation for full instructions on how
to install and use it. What follows is an example of how to run Dr. Watson
and use the information supplied.
1. Run file %windir%\system32\drwtsn32.exe. This opens a window that
allows you to configure Dr. Watson.
v The log file path defaults to %windir%.
v A crash dump is a binary system dump, and can be large. Clear
the Create Crash Dump File checkbox if you do not want a binary
system dump.
230 CICS Transaction Gateway: Windows Administration

Diagnosing common problems: Client daemon
2. Leave Dr. Watson running, and recreate the trap scenario.
3. When a window appears saying that a trap has occurred, press
cancel to debug the application.
4. Click OK when prompted, to create the log file.
5. You can now open the log file (drwtsn32.log) to determine which
process trapped.
6. Near the top of the log are entries that give the process id (pid) of
the trapping process:
*----> System Information Task List

|
|
|
Diagnosing common problems: Client daemon
10. The task list shows which tasks were running at the time the trap
occurred, and shows which address of memory they were loaded
into. You can cross-reference this with the fault address to work out
which file the trap occurred in.
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 213, 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 trace wrapping if you
do not want the trace file to get too large; see “Tracing” on page 209.) 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?
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
232 CICS Transaction Gateway: Windows Administration

v Monitoring information
v Execution diagnostic facility (EDF)
v CICS-supplied transactions, CEBR and CECI
v Independent software vendor (ISV) tools
CICS server problem determination
Information about these facilities is given in the Problem Determination books
for the individual products (see “CICS Transaction Server publications” on
page 267). 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 Transaction Gateway and CICS Universal Client
FAA CICS for OS/2
DFH CICS on System/390 ® and z/OS
ERZ Transaction Server for Windows NT Version 4.0, and TXSeries
AEG CICS for OS/400.
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 very 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: 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.
IPCONFIG Displays all current TCP/IP network
Chapter 14. Problem determination and problem solving 233

Communication problems
configuration values. This is helpful if you
have to find out if an IP interface is active.
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.
TRACERT 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.
SNA Server: See the Microsoft SNA Server Administration Guide for information
on diagnostic tools that you can use with SNA Server.
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
234 CICS Transaction Gateway: Windows Administration

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.
Communication problems
If you cannot acquire the connection, SNA is wrongly configured on the
product or the host.
IBM Communications Server for Windows NT and Windows 2000: IBM
Communications Server writes a log file called pcwmsg.mlg, which can help to
diagnose communications errors. Because it is a text file, you can view it in
any text editor, or you can use the supplied Communications Server Log Viewer
utility. The viewer includes online help.
Use the supplied Getsense utility to understand error messages that contain
sense codes.
Your IBM support organization will need the log file if you have SNA errors
that you cannot resolve. They may also ask you for a trace. To turn trace on,
select the Communications Server Trace Facility. The trace facility has options to
start and stop the trace, save it, and format it to a text file. IBM support will
probably ask you to trace these components:
Function Component Trace options
APPN ® and APPC Nof API Verb trace up to 128 bytes
APPC API Verb trace up to 128 bytes
Connectivity (Your network type) Verb trace up to 128 bytes
For more details, see your IBM Communications Server documentation.
Chapter 14. Problem determination and problem solving 235

Program Support
Program support
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/ts/cics/
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
236 CICS Transaction Gateway: Windows Administration

Program Support
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 240. If the RETAIN search is unsuccessful, the
problem is passed on to a Level-2 representative 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 239. 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 240.
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.
Chapter 14. Problem determination and problem solving 237

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Program Support
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.
v A 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 5.0, together with the number of any PTF or other fix
applied, for example UNnnnnn (where nnnnn is a valid PTF number).
v Obtain Windows operating system details by using the WINVER.EXE
command at a command prompt.
If you are using SNA Server, you can find its version number by entering
the SNAVER.EXE command.
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.
238 CICS Transaction Gateway: Windows Administration

Program Support
– 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.
When deciding the severity of the problem, take care to categorize it
correctly, as the procedures followed by the support organization depend
on the severity level supplied.
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.
v If you upload files to a mainframe system, do so in binary rather than
ASCII format.
APARs and fixes
Once 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
Chapter 14. Problem determination and problem solving 239

Program Support
error, and in time, 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/details.
240 CICS Transaction Gateway: Windows Administration

Chapter 15. Migration
This chapter 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. Topics covered include:
v “Migrating from CICS Client Version 2” on page 243
v “Migrating from CICS Universal Client, or CICS Transaction Gateway,
Version 3” on page 243
v “Migrating from CICS Gateway for Java” on page 244
v “Migrating from the CICS Internet Gateway” on page 245
v “Migrating from CICS Gateway for Lotus Notes ” on page 248
v “EPI beans provided in earlier versions of the CICS Transaction Gateway”
on page 248
See also “Upgrading” on page 30.
The configuration conversion tool
The configuration conversion tool (ctgconv) converts the configuration files of
versions of the following to the current format:
v CICS Transaction Gateway v3.0
v CICS Universal Client v3.0
v CICS Client Version 2
v CICS Gateway for Java
If the CICS Transaction Gateway Version 5.0 installation upgrades your
existing product, the configuration conversion tool runs automatically if it
finds configuration files in the old format. If you have to uninstall the earlier
product first, or your configuration files cannot be found during the upgrade,
run ctgconv after installation.
The conversion tool converts the following:
Gateway.properties
Properties file of CICS Transaction Gateway Version 3.0 and CICS
Gateway for Java.
CICSCLI.INI
Client initialization file of CICS Clients Version 2 and Version 3.0.
© Copyright IBM Corp. 1996, 2002 241

Migration
CICSX.INI
Workload Manager configuration file of CICS Universal Clients for
Windows Version 3.0.
The conversion tool produces one output file called CTG.INI by default.
Old files are renamed with the BAK extension.
Using the conversion tool
The parameters of ctgconv are:
ctgconv −c=file [−g=file] [−l=file] [−o=file]
For each parameter, file can be any of the following:
v A filename and extension; the \bin directory is assumed.
The extension must be INI, except for the CICS Transaction Gateway
Version 3.0 and CICS Gateway for Java input files, which have the
properties extension.
v A full pathname.
v A directory name (without a trailing \); the default filename is assumed.
−c=file
Specifies the Client initialization file to be converted. If file specifies a
directory, a filename of CICSCLI.INI is assumed.
If the parameter is not specified, the CICSCLI environment variable is
used to locate the Gateway initialization file. If CICSCLI is not set, the file
CICSCLI.INI, in the \bin subdirectory, is assumed.
−g=file
Specifies the Gateway.properties file to be converted. If you do not
specify this parameter, no Gateway section is created in CTG.INI.
−l=file
Specifies the Workload Manager configuration file to be converted. If you
specify a directory, the filename CICSX.INI is assumed. If you do not
specify this parameter, the CICSX_CONFIG_URL environment variable is
used to locate the file. If this environment variable is not set, the default
file in the \bin subdirectory is assumed.
If no Workload Manager configuration file exists, no Workload Manager
section is created in CTG.INI.
−o=file
Specifies the pathname of the converted file. The default is CTG.INI, inthe
\bin subdirectory.
For help on using ctgconv, enter ctgconv −?
242 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
During conversion, the input files are renamed so that the last three characters
of the file extension become BAK. Any file with that name is overwritten, and
any output file that exists before the conversion is renamed in the same way.
A banner is inserted into the renamed files stating that they are obsolete.
Redundant parameters are removed from the old configuration files, and
other parameters are given new names in the converted file.
Migrating from CICS Client Version 2
You might have customized versions of the following configuration files:
File Default Name
Keyboard mapping file CICSKEY.INI
Color mapping file CICSCOL.INI
Window settings CICSTERM.INI
Follow these steps:
1. Take a copy of any customized configuration files, including CICSCLI.INI
2. Delete CICS Client Version 2.
3. Install the CICS Transaction Gateway Version 5.0
4. Run the configuration conversion tool (ctgconv) to convert CICSCLI.INI to
the new format; see “The configuration conversion tool” on page 241.
Migrating from CICS Universal Client, or CICS Transaction Gateway, Version 3
The following are not supported:
v PL/I
v REXX
v CICSTELD
v Windows ® 95, Windows 98, OS/2 ®
v 16-bit applications
v NetBIOS and DCE protocols
v IBM VisualAge C++ for Windows
v Novell Netware for SAA ®
v The CICSCLI -f parameter
Migration
TCP62 multiple server definitions
Multiple server definitions with identical combinations of Local LU, Partner
LU, and Mode name are not permitted in CTG.INI in the CICS Transaction
Gateway Version 5.0. This ensures that every connection that the CICS region
and the network protocol see is represented by a unique server definition in
Chapter 15. Migration 243

|
|
|
|
Migration
the configuration file. Existing Client applications that use different server
names to send requests to the same CICS region continue to work if a user
exit is defined to redirect requests. A sample user exit that does this is
provided; see \samples\samples.txt.
You might have customized versions of the following configuration files:
File Default Name
Keyboard mapping file CICSKEY.INI
Color mapping file CICSCOL.INI
Windows settings CICSTERM.INI
When you install CICS Transaction Gateway Version 5.0 your customized files
are preserved, even though CICS Universal Client Version 3.0 is deleted.
In CICS Transaction Gateway Version 5.0 the configuration file (CTG.INI),
replaces the Client initialization file (CICSCLI.INI).
The new file also replaces the Workload Manager configuration file, and the
Gateway.properties file.
These files are automatically converted to the correct format when you install
Version 5.0, if the files are found on upgrade.
Migrating from CICS Gateway for Java
1. Take a copy of your Gateway.properties file.
2. Delete the CICS Gateway for Java.
3. Install the CICS Transaction Gateway Version 5.0.
4. Use the configuration conversion tool to convert your Gateway.properties
file; see “The configuration conversion tool” on page 241.
Change all import statements in your programs and recompile them. Change
all occurrences of:
import ibm.cics.jgate.client.* to: import com.ibm.ctg.client.*
import ibm.cics.jgate.epi.* to: import com.ibm.ctg.epi.*
import ibm.cics.jgate.security.* to: import com.ibm.ctg.security.*
Modify any programs written for the CICS Gateway for Java prior to Version
2.0.1 that use the Session interface. This is because the parameter to the
Session.handleReply method was changed to TerminalInterface instead of a
Terminal object. Change and then recompile your programs.
244 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
Due to a change in the ClientSecurity and ServerSecurity interfaces, any user
classes that implement these methods need to be changed. The TCP/IP
address of the remote computer is now passed to the methods called to
generate handshake data. An afterDecode method has also been added to
both interfaces. See Programming in Java, inCICS Transaction Gateway:
Programming Guide, for more information.
Migrating from the CICS Internet Gateway
This section describes how to migrate from using the CICS Internet Gateway
to using the Terminal Servlet.
Read Chapter 13, “The Terminal Servlet program” on page 187 before you
perform migration, to familiarize yourself with the concepts of the Terminal
Servlet.
The CICS Internet Gateway reads settings from a configuration file, which is
called cigd.ini.
CICS Internet Gateway default settings
Migration
CICS Internet Gateway Terminal Servlet equivalent
Cursor The Cursor key equivalent. There is no
equivalent setting for the Terminal Servlet.
Instead, you can use JavaScript to set the
position of the cursor. To allow this, set the
servlet property screen@cursoring to true.
Info Filename for the information file for the server
(for AIX and Windows NT). There is no
equivalent setting for the Terminal Servlet.
Error Filename for the error file for the server. There
is no equivalent setting for the Terminal
Servlet.
Trace Filename for the trace file for the server. There
is no equivalent setting for the Terminal
Servlet. Servlets write logging information to
the servlet log provided by the Web server.
See your Web server documentation to find
out where this file is. If trace is turned on it is
written to the standard output. Depending on
your Web server, this may be directed to a file.
MaxUsers The maximum number of users. The
equivalent servlet property is
pool@maxTerminals.
Chapter 15. Migration 245

Migration
TimeOutCICS The “Wait for CICS ” timeout. The servlet
property servlet@allocateTimeout limits the
time that the servlet will wait for a terminal to
be connected to CICS. There is no limit on the
time the servlet will wait for CICS to respond
in other situations.
TimeOutGateway The “Wait for Gateway” timeout. There is no
equivalent setting for the Terminal Servlet.
TimeOutInternet The “Wait for Internet” timeout. The servlet
property pool@idleTimeout limits the time
that the servlet will let a terminal be unused
before it is disconnected.
CICS Internet Gateway override settings
CICS Internet Gateway Terminal Servlet equivalent
AutoExit Normally, the Terminal Servlet does not
disconnect the terminal when a transaction
ends. If this is the behavior you want, set the
page mapping property page@idle to the URL
/servlet/TerminalServlet?request=disconnect,
replacing TerminalServlet with the name of an
instance of the Terminal Servlet on your Web
server.
ExitAid The Exit key equivalent. The servlet uses
Screen Handler beans to exit running
transactions. You can generate and customize
Screen Handler beans for specific CICS
screens, and you can create a default Screen
Handler that knows how to exit a range of
transactions. The supplied sample
DefaultScreenHandler exits using the AID PF3.
ExitPage The URL for the HTML exit page. Use the
page mapping property page@disconnected to
specify a page to be displayed when the
terminal is disconnected.
ImbedHTML Allows Imbedded HTML. The servlets default
behavior is to write out the contents of CICS
screens as is, that is, text taken from the CICS
screen is assumed to be correct HTML. If the
characters , or & are present on the CICS
screen, this may cause problems. To translate
the characters , and & to < > and
& respectively, set the request parameter
246 CICS Transaction Gateway: Windows Administration

Migration
translateText to true. No translation is
performed when sending data to CICS.
Header The filename for the HTML header. There is
no equivalent setting for the Terminal Servlet.
Trailer Filename for the HTML trailer. There is no
equivalent setting for the Terminal Servlet.
GraphicKeys Display the keys as GIFs. There is no
equivalent setting for the Terminal Servlet.
PAKeys Display the PA keys. There is no equivalent
setting for the Terminal Servlet.
PFKey24 Display extra row of PF keys. There is no
equivalent setting for the Terminal Servlet.
Output from the Terminal Servlet is inserted
into a Web page that you provide. The sample
file epissam1.shtml is provided as a starting
point.
CICS Internet Gateway actions
The CICS Internet Gateway is invoked by an HTML form. To invoke the
Terminal Servlet instead, change the action to /servlet/servlet where
servlet is TerminalServlet or another name.
Query the current gateway settings
You can query the various servlet properties individually. See
“Displayable properties” on page 205 for details.
List the available CICS systems
The servlet does not provide this function. Each Terminal Servlet
instance can connect to only one CICS server. You should configure an
instance of Terminal Servlet for each CICS server that you want to
allow users to connect to.
Start a transaction
You must add a hidden element setting the name ″request″
to the value ″send″, as in Table 10
Table 10. Terminal Servlet equivalents of actions
CICS Internet Gateway
element name
Terminal Servlet equivalent
SystemName None
TranName transaction
TranData transactionData
AutoExit page@idle=/servlet/TerminalServlet?request=disconnect
is equivalent to AutoExit=On
Chapter 15. Migration 247

|
|
|
|
|
Migration
Table 10. Terminal Servlet equivalents of actions (continued)
CICS Internet Gateway
element name
Terminal Servlet equivalent
ExitAID None
ExitPage page@disconnected
ImbedHTML translateText=true is equivalent to ImbedHTML=Off
Anything else None
See “Properties and parameters reference” on page 200 for more information.
Administration functions
You can query the number of terminals that are in use and turn trace on and
off. However, these functions cannot be restricted to administrators.
Migrating from CICS Gateway for Lotus Notes
CICS Clients Version 2 included the CICS Gateway for Lotus Notes, also
known as CICS Link for Lotus. This is not available in CICS Transaction
Gateway Version 5.0.
For inter-operation of CICS and Lotus Notes ® , IBM recommends that you use
the MQSeries ® Enterprise Integrator, which offers these advantages over the
CICS Gateway for Lotus Notes:
v A common API that you can use to integrate Lotus Notes with IMS or
MQSeries as well as CICS
v Support for the EPI and ECI
v Use it straight from a Web browser connected to Lotus Domino
MQSeries Enterprise Integrator is included in MQSeries and CICS
Connections for Domino. For more information, visit the Web site at:
www.lotus.com/
and follow the Products link.
EPI beans provided in earlier versions of the CICS Transaction Gateway
These beans, which previously were provided as part of the CICS Transaction
Gateway product, are now included with the set of sample programs:
v EPIMonitor
v EPIScreenButtons
v EPIBasicScreenHandler
248 CICS Transaction Gateway: Windows Administration

|
|
|
|
Migration
Include the archive \classes\ctgsamples.jar in the classpath
of any programs that use these beans. The EPIBasicScreenHandler bean
includes new functions, such as font and color selection, and an improved
layout.
Chapter 15. Migration 249

250 CICS Transaction Gateway: Windows Administration

Appendix A. Data conversion between the Client daemon
and a CICS server
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/390 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.
Data conversion on Windows
The ASCII CCSID is determined dynamically. By default the GetOEMCP
function is used to obtain the current OEM code page identifier, for example
CCSID 850, for the system. If the Use OEM codepage configuration setting is
specified, the GetACP function is used to obtain the current ANSI code page
identifier, for example CCSID 1252, for the system.
The identifier may not be unique. For example, there are differences between
IBM CCSID 932 and Microsoft CCSID 932 - the Client daemon maps the
Microsoft one to CCSID 943 which is the equivalent one defined in the CRDA
Registry. The Microsoft CCSID 1252 may be the pre-euro or post-euro version
- the post-euro is mapped to CCSID 5348.
© Copyright IBM Corp. 1996, 2002 251

Data conversion
Supported conversions
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 table has been extracted from Communicating from CICS on
System/390, SC33-1697. 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 intent is that other CICS servers will
provide equivalent support.
Arabic:
CCSID CPGID
ASCII 00864 00864 PC data: Arabic
01089 01089 ISO 8859-6: Arabic
01256 01256 MS Windows: Arabic
EBCDIC 00420 00420 Host: Arabic
Baltic Rim:
CCSID CPGID
ASCII 00921 00921 PC data: Latvia, Lithuania
01257 01257 MS Windows: Baltic Rim
EBCDIC 01112 01112 Host: Latvia, Lithuania
Cyrillic:
CCSID CPGID
ASCII 00866 00866 PC data: Cyrillic
00915 00915 ISO 8859-5: Cyrillic
01251 01251 MS Windows: Cyrillic
EBCDIC 01025 01025 Host: Cyrillic multilingual
Estonia:
CCSID CPGID
ASCII 00922 00922 PC data: Estonia
01257 01257 MS Windows: Baltic Rim
EBCDIC 01122 01122 Host: Estonia
Greek:
CCSID CPGID
ASCII 00869 00869 PC data: Greece
00813 00813 ISO 8859-7: Grek
01253 01253 MS Windows: Greek
EBCDIC 00875 00875 Host: Grek
Hebrew:
252 CICS Transaction Gateway: Windows Administration

CCSID CPGID
ASCII 00856 00856 PC data: Hebrew
00916 00916 ISO 8859-8: Hebrew
01255 01255 MS Windows: Hebrew
EBCDIC 00424 00424 Host: Hebrew
Latin-1:
CCSID CPGID
ASCII 00437 00437 PC data: USA, many other countries
00819 00819 ISO 8859-1: Latin-1 countries
00850 00850 PC data: Latin-1 countries
01252 01252 MS Windows: Latin-1 countries
EBCDIC 00037 00037 Host: USA, Canada, etc
00273 00273 Host: Austria, Germany
00277 00277 Host: Denmark, Norway
00278 00278 Host: Finland, Sweden
00280 00280 Host: Italy
00284 00284 Host: Spain, Latin America (Spanish)
00285 00285 Host: United Kingdom
00297 00297 Host: France
00500 00500 Host: International Latin-1
00871 00871 Host: Iceland
01047 01047 Host: Latin-1 Open Systems
Latin-1 including euro support:
CCSID CPGID
ASCII 00858 00858 PC data: Latin-1 countries
05348 01252 MS Windows: Latin-1 countries, version 2
EBCDIC 01140 01140 Host: USA, Canada, etc
01141 01141 Host: Austria, Germany
01142 01142 Host: Denmark, Norway
01143 01143 Host: Finland, Sweden
01144 01144 Host: Italy
01145 01145 Host: Spain, Latin America (Spanish)
01146 01146 Host: United Kingdom
01147 01147 Host: France
01148 01148 Host: International Latin-1
01149 01149 Host: Iceland
Latin-2:
CCSID CPGID
ASCII 00852 00852 PC data: Latin-2 multilingual
00912 00912 ISO 8859-2: Latin-2 multilingual
01250 01250 MS windows: Latin-2
EBCDIC 00870 00870 Host: Latin-2 multilingual
Latin-5:
CCSID CPGID
ASCII 00857 00857 PC data: Latin-5 (Turkey)
00920 00920 ISO 8859-9: Latin-5 (Turkey)
01254 01254 MS Windows: Turkey
EBCDIC 01026 01026 Host: Latin-5 (Turkey)
Data conversion
Appendix A. Data conversion between the Client daemon and a CICS server 253

Data conversion
Latin-9:
CCSID CPGID
ASCII 00923 00923 ISO 8859-15: Latin-9
EBCDIC 00924 00924 Host: Latin-9
Japanese:
CCSID CPGID
ASCII 00932 00897 PC data: SBCS
00301 PC data: DBCS
00942 01041 PC data: extended SBCS
00301 PC data: DBCS
00943 00897 PC data: SBCS
00941 PC data: DBCS for Open environment
00954 00895 G0: JIS X201 Roman
00952 G1: JIS X208-1990
00896 G2: JIS X201 Katakana
00953 G3: JIS X212
EBCDIC 00930 00290 Host: Katakana, extended SBCS
00300 Host: DBCS
00931 00037 Host: Latin-1, SBCS
00300 Host:DBCS
00939 01027 Host: Latin-1, extended SBCS
00300 Host: DBCS
Korea:
CCSID CPGID
ASCII 00934 00891 PC data: SBCS
00926 PC data: DBCS
00944 01040 PC data: extended SBCS
00926 PC data: DBCS
00949 01088 PC data: SBCS, IBM KS code
00951 PC data: DBCS, IBM KS code
00970 00367 G0: ASCII
00971 G1: KSC X5601-1989
01363 01126 MS Windows: Korean SBCS
01362 MS Windows: Korean DBCS
EBCDIC 00933 00833 Host: extended SBCS
00834 Host: DBCS
Simplified Chinese:
CCSID CPGID
ASCII 00946 01042 PC data: extended SBCS
00928 PC data: DBCS
01381 01115 PC data: extended SBCS, IBM GB
01380 PC data: DBCS, IBMGB
01383 00367 G0: ASCII
01382 G1: GB 2312-80 set
01386 01114 PC data: SBCS, S-Chinese GBK,
T-Chinese IBM BIG-5
01385 PC data: DBCS, S-Chinese GBK
EBCDIC 00935 00836 Host: extended SBCS
00837 Host: DBCS
254 CICS Transaction Gateway: Windows Administration

Traditional Chinese:
CCSID CPGID
ASCII 00938 00904 PC data: SBCS
00927 PC data: DBCS
00948 01043 PC data: extended SBCS
00927 PC data: DBCS
00950 01114 PC data: SBCS, IBM BIG-5
00947 PC data: DBCS
00964 00367 G0: ASCII
00960 G1: CNS 11643 plane 1
00961 G2: CNS 11643 plane 2
EBCDIC 00937 00037 Host: Latin-1 SBCS
00835 Host: DBCS
Data conversion
Appendix A. Data conversion between the Client daemon and a CICS server 255

Data conversion
256 CICS Transaction Gateway: Windows Administration

Appendix B. Hardware and software
This chapter lists hardware requirements and supported software for all
operating systems on which the CICS Transaction Gateway runs.
Hardware requirements
This section discusses the disk space requirements on z/OS, and general
hardware requirements on distributed platforms.
Disk space requirements on z/OS
CICS Transaction Gateway is normally installed into a directory such as
/usr/lpp/ctg, in USS (see also “Installation path” on page xii). In this case,
during installation, the uncompressed tar file is present in the /usr/lpp
directory. The HFS data set for this directory must be large enough to take the
25MB (40 cylinders) that this file occupies. You can delete the files once
installation is complete. Installation also requires 25MB (40 cylinders) in the
/tmp directory.
Once installed, CICS Transaction Gateway occupies 27MB. You need enough
disk space for CICS Transaction Gateway and any logging and tracing files.
IBM recommends that you use a separate HFS data set with a primary
allocation of 40 cylinders for CICS Transaction Gateway software. Increase this
to 50 cylinders if the logging and trace files will be stored in the same HFS
data set. Increase it further if many instances of CICS Transaction Gateway
will run, or if much logging is required. Alternatively, you can use a separate
HFS data set, with a primary allocation of 5 cylinders, for each instance of
CICS Transaction Gateway.
If you use the existing /usr/lpp HFS data set, ensure it has enough space to
take the CICS Transaction Gateway software.
Table 11. Hardware requirements on UNIX systems
AIX LINUX SOLARIS HP-UX
Processor v IBM RISC
System/6000 ®®
v IBM RS/6000 ®®
Scalable
POWERParallel
System (SP2 ® G5, G6, MP3000 or
above
SPARC PA-RISC 1.1 or 2.0
).
© Copyright IBM Corp. 1996, 2002 257

Table 11. Hardware requirements on UNIX systems (continued)
AIX LINUX SOLARIS HP-UX
Terminals Any type of Any standard Any type of Any standard
terminal or telnet or X based terminal or telnet or X based
X/Terminal that terminal that can X/Terminal that terminal that can
can attach to the access Linux. can attach to the access HP-UX.
processor.
processor.
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB
Disk space 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB
for temporary files for temporary files for temporary files for temporary files
used during used during used during used during
installation. installation. installation. installation.
Table 12. Hardware requirements on Windows systems
Processor Any processor capable of running the appropriate
operating system and other prerequisite software.
Network adapters To connect workstations to the LAN, you need a
suitable adapter such as an ethernet adapter.
Memory At least 64 MB.
Disk space You need 30 MB of free disk space for your CICS
Transaction Gateway (including documentation in US
English only).
Supported software
The following products are supported.
You need a further 30 MB for temporary files used
during installation. At least 12 MB of this must be on
your system partition.
Operating systems
CICS Transaction Gateway is supported on the following operating systems:
v AIX V4.3.3 with Service Pack 25
v AIX 5.1
v HP-UX 11.0
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)
v Linux for S/390 ® - SuSE 7.0 (Kernel level 2.2.16)
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)
258 CICS Transaction Gateway: Windows Administration

v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)
v OS/390 V2.10
v z/OS V1.2
v Windows XP Professional
v Windows 2000 Professional with a minimum of Service Pack 1
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a
minimum of Service Pack 1
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a
v Windows NT Server V4.0 with a minimum of Service Pack 6a.
Notes:
– Windows NT 4 Terminal Server is not supported
– The setting of multiple user interface languages, under Windows
2000 MultiLanguage Version, is not supported.
– If you plan to run CICS Transaction Gateway under load, and
using remote protocols, it is strongly recommended that you use
a server version, rather than a workstation version, of Windows.
See “ConnectFailed exceptions when running under load” on
page 216, for more information.
Web browsers
v HTML/HTTP functions: Any browser that supports HTML V1.0 should
work with the product.
v Java Functions: Any JDK 1.1 compliant Web browser should work with the
product.
The CICS Transaction Gateway is supported with the following browsers:
v Microsoft Internet Explorer 5.0, 5.5 and 6.0
v Netscape Communicator 4.7 and 6.2
v HotJava Browser V 1.1 (for Solaris)
Note: Applets running within the JVM supplied with the Netscape
Communicator browser fail to make successful connections with the
CICS Transaction Gateway. Message number CCL6652E is returned to
the applet. Currently there is no solution to this problem.
Java applets are supported for compatibility with previous versions of
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.
Appendix B. Hardware and software 259

|
|
|
|
|
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 going in
as. Currently there is no solution to this problem.
JDK levels
CICS Transaction Gateway supports JDK levels 1.3 and 1.3.1 at the following
minimum service levels:
v AIX: IBM Java SDK 1.3 (service release 6)
v HP-UX: Java SDK 1.3.0.02
v Solaris: Sun Java SDK SE 1.3.0_04.
v z/OS: IBM Java SDK 1.3
If using the IBM Persistent Reusable JVM, you are recommended to run at a
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable
functionality of this JVM.
If using Java under DBCS code pages, especially IBM-939, install service
refresh 14 or later.
v Windows: IBM Java SDK 1.3 (service release 6)
JSSE
CICS Transaction Gateway supports JSSE in the the following environments:
v Standard Java runtime environment (JRE).
Only the IBM JSSE is supported:
– AIX: Install the JSSE package supplied with CICS Transaction Gateway
– HP-UX: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
– Linux for S/390: Install the JSSE package supplied with CICS Transaction
Gateway
– Solaris: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
– z/OS with JRE 1.3.1: includes a version of JSSE that CICS Transaction
Gateway supports
– Windows: Install the JSSE package supplied with CICS Transaction
Gateway
v WebSphere Application Server:
All supported levels have built in JSSE support.
CICS Transaction Gateway does not support the use of JSSE with applets.
260 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
CICS Servers
A CICS server runs real-time multi-user applications and manages the
associated resources and data. CICS Transaction Gateway is supported with
the following servers:
v CICS Transaction Server for z/OS V2.2
v CICS Transaction Server for z/OS V2.1 (with APAR PQ30168, for signon
capable terminals, applied)
v CICS Transaction Server for z/OS V1.3 with APAR PQ30168, for signon
capable terminals, applied.
v CICS for MVS/ESA V4.1, with communication through SNA. (with APAR
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for
EPI emulation. APAR PN79262 is needed for DBCS support.
v CICS for OS/400 V4.4
v CICS Transaction Server for OS/2 V4.1 with CSD 3
v CICS Transaction Server for VSE/ESA 1.1.0 (with APAR PQ30170, for
signon capable terminals, applied), or a minimum service level of 1.1.1
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)
v TXSeries V5.0 (Windows, AIX)
Web servers
Any web server that is supported by your application server should work
with the product.
Application servers
The CICS Transaction Gateway is supported with the following:
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,
AIX and Solaris.
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF
UQ99329 (Service Level W401030).
SNA communications
Customers wishing to use SNA communications should install one of the
following products:
Windows operating systems
Any one of:
v IBM eNetwork Communications Server V6.1, with a minimum of
service level 1
v IBM eNetwork Personal Communications V5.0, with a minimum of
service level 2
v IBM eNetwork Personal Communications V5.5
Appendix B. Hardware and software 261

v Microsoft SNA Server V4.0 with a minimum of SP4
AIX
IBM eNetwork Communications Server V6.1, with a minimum of service
level 1 (AIX).
SNA is not supported on other UNIX operating systems.
TCP/IP communications
TCP/IP support is provided by the operating system.
TCP62 communications
TCP62 support is provided by CICS Transaction Gateway.
Compilers and application development tools
CICS Transaction Gateway is supported with the following compilers and
application development tools:
AIX
v IBM C for AIX V4.4
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6
v IBM VisualAge C++ Professional V4.0
v IBM VisualAge C++ Professional V5.0 (requires AIX version 4.2 or later)
HP-UX
v HP ANSI C B.11.01, with a minimum of service level 7
v HP aC++ B.11.01, with a minimum of service level 6
Linux for S/390
v GNU compiler C runtime V2.95, with a minimum of service level 2
v GNU compiler C++ runtime V2.95, with a minimum of service level 2
Solaris
Sun WorkShop C++ V5.0
Note: The C++ compiler must have all available service patches applied.
Windows
v IBM VisualAge COBOL V3.0
v Microsoft Visual C++ V6.0
v Microsoft Visual Basic V6.0
v Microsoft Visual Basic Script (VBScript) V5.0
Note: The CICS Transaction Gateway does not support use of the COM
libraries with Microsoft Transaction Server (MTS), or the MTS
component of COM+.
262 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
Screen readers
The CICS Transaction Gateway is supported with JAWS.
Other tools
These tools are available for viewing the PDF online documents:
v Adobe Acrobat Reader V5.0
v GhostView V4.0 on Linux
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.
Appendix B. Hardware and software 263

264 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The product library and related literature
This chapter lists books on the CICS Transaction Gateway, and related topics.
It also discusses how you can view the online library supplied with the
product.
It consists of the following topics:
“CICS Transaction Gateway books” Read this for a list of all books provided
with the CICS Transaction Gateway.
“Sample configuration documents” on
page 266
Read this for information about a series of
PDF documents that provide step-by-step
guidance on configuring the CICS
Transaction Gateway.
“Redbooks” on page 267 Read this for details of other publications
that contain examples of client/server
configurations.
“Other Useful Books” on page 267 Read this for details of other relevant
publications.
“Obtaining books from IBM” on page 269 Read this for information on downloading
books and ordering hardcopy versions.
CICS Transaction Gateway books
v CICS Transaction Gateway: Windows Administration, SC34-6190
This book describes the administration of the CICS Transaction Gateway for
Windows.
v CICS Transaction Gateway: UNIX Administration, SC34-6139
This book describes the administration of the CICS Transaction Gateway for
UNIX operating systems.
v CICS Transaction Gateway: z/OS Administration, SC34-6191
This book describes the administration of the CICS Transaction Gateway for
z/OS.
v CICS Transaction Gateway: Gateway Messages
This online book lists and explains the error messages that can be generated
by CICS Transaction Gateway.
You cannot order this book.
v CICS Transaction Gateway: Programming Reference, SC34-6140
© Copyright IBM Corp. 1996, 2002 265

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The CICS Transaction Gateway
This book provides information on the APIs of the programming languages
supported by the CICS Transaction Gateway.
There are also additional HTML pages that contain JAVA programming
reference information.
v CICS Transaction Gateway: Programming Guide, SC34-6141
This introduction to programming for the CICS Transaction Gateway
provides the information that you need to allow non-CICS applications to
use CICS facilities in a client/server environment.
Sample configuration documents
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. .
The following scenarios are currently covered:
v Configuring CICS Transaction Gateway for Windows for Microsoft SNA
Server
v Configuring CICS Transaction Gateway for Windows for eNetwork Personal
Communications
v Configuring CICS Transaction Gateway for Windows for TCP62
v Configuring CICS Transaction Gateway for AIX for IBM eNetwork
Communications Server
v Configuring CICS Transaction Gateway for Windows for Communications
Server
v Configuring CICS Transaction Gateway for Terminal Servlets using
WebSphere Application Server for Windows
v Client security configuration
v Configuring CICS Transaction Gateway for WebSphere 4.01 using J2EE
v Configuring CICS Transaction Gateway 4.02 for WebSphere Application
Server on z/OS using J2EE
As more sample configuration documents become available, you can
download them from our Web site at:
www.ibm.com/software/ts/cics/
and follow the Download link.
266 CICS Transaction Gateway: Windows Administration

Redbooks
Other Useful Books
The following International Technical Support Organization (ITSO) Redbook
publication contains many examples of client/server configurations:
v CICS Transaction Gateway V3.1 The WebSphere Connector for CICS, SG24-6133
This book supersedes the following book:
v Revealed! CICS Transaction Gateway with more CICS Clients Unmasked,
SG24-5277.
v Java Connectors for CICS: Featuring the J2EE Connector Architecture, SG24-6401.
This book provides information on developing J2EE applications.
See also:
v Securing Web Access to CICS, SG24–5756.
v Workload Management for Web Access to CICS, SG24–6118.
You can obtain ITSO Redbooks from a number of sources. For the latest
information, see:
www.ibm.com/redbooks/
CICS Transaction Server publications
Other publications
CICS interproduct communication
The following books describe the intercommunication facilities of the CICS
server products:
CICS Family: Interproduct Communication, SC34-6030
Transaction Server for Windows NT: Intercommunication, SC33-1882
CICS Transaction Server for z/OS: Intercommunication Guide, SC34-6005
CICS Transaction Server for VSE/ESA: Intercommunication Guide, SC33-1665
CICS for OS/400: Intercommunication, SC33-1388
TXSeries: CICS Intercommunication Guide, SC09-3900
CICS for OS/2: Intercommunication, SC33-1583
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:
Transaction Server for Windows NT: Problem Determination, GC33-1883
CICS Transaction Server for z/OS ® Problem Determination Guide, SC34-6002
The product library and related literature 267

Other publications
CICS Transaction Server for VSE/ESA Problem Determination Guide,
GC33-1663
CICS for OS/400 ® : Problem Determination, SC33-1384
TXSeries: CICS Problem Determination Guide, SC33-1565.
You can find information on CICS products at the following Web site:
www.ibm.com/software/ts/cics/
Microsoft ® Windows Family publications
The following book provides introductory material about the Windows Family
of operating systems:
v Windows NT System Guide
APPC-related publications
The following books are concerned with products providing APPC support:
IBM products
IBM Communications Server for Windows NT and Windows 2000:
Communications Server for Windows: Quick Beginnings, GC31-8424
IBM Communications Server for AIX for AIX:
IBM Communications Server for AIX: Quick Beginnings, GC31-8583
IBM Communications Server for AIX: General Information, GC31-8584
IBM Communications Server for AIX: Administration, SC31-8586
IBM Communications Server for AIX: Administration Command Reference,
SC31-8587
IBM eNetwork Personal Communications:
IBM Personal Communications for Windows NT: Quick Beginnings,
GC31-8679-02
IBM Personal Communications: Administrator’s Reference, SC31-8840
Microsoft products
Microsoft SNA Server Installation Guide
Microsoft SNA Server Administration Guide
Microsoft SNA Server Reference
Systems Network Architecture (SNA)
SNA Formats, GA27-3136
Systems Network Architecture Technical Overview, GC30-3073
268 CICS Transaction Gateway: Windows Administration

TCP62–related publications
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
GC31–7073
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074
Obtaining books from IBM
For information on books you can download, visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link.
You can order hardcopy books:
v Through your IBM representative or the IBM branch office serving your
locality.
v By calling 1-800-879-2755 in the United States.
v From the Web site at:
www.ibm.com/shop/publications/order
Other publications
The product library and related literature 269

270 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Accessibility
The English version of the CICS Transaction Gateway has been tested for
accessibility on the Windows operating system. The product is accessible.
Documentation
Download the CICS Information Center for an html version of the
documentation. Go to this Web page
www.ibm.com/software/ts/cics/
Installation
iKeyMan
Samples
and follow the Library link.
The following are known issues:
v Screen readers do not read the progress bars that appear during the various
phases of installation.
v The installation program does not support system settings for font size and
font colors.
These shortcut keys activate options from the installation options screen:
Alt+C Install the CICS Transaction Gateway.
Alt+J Install Java.
See this Web site for information:
www.tivoli.com
The samples are not accessible.
Configuration tool accessibility
Components
Each component in the configuration tool has a name and description for
screen readers.
© Copyright IBM Corp. 1996, 2002 271

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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+letter
Certain actions have shortcuts assigned to them. Hold down the Ctrl key
and type the letter to do the action.
Ctrl+letter Action
C Copies the selected value.
N Creates a new configuration.
O Opens an existing configuration.
P Pastes.
S Saves the current configuration.
U Cuts the selected value.
V Pastes.
W Creates a new server definition.
X Cuts the selected value.
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 tree 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 tree is active.) Move up and down through the tree.
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.
Control+Page Up
Scroll left.
Control+Page Down
Scroll right.
272 CICS Transaction Gateway: Windows Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Control+Tab
Use this (rather than Tab) on panels that contain a table to cycle between
the tree, objects on the panel, and the buttons. Use Control+Shift+Tab to
move backwards.
Enter
Activates a button in the Task Guide.
Escape
Closes the menu.
F2 Select and change an editable number field in a table, for example the
Bias value field on the Program definition for managing workload panel.
F6 (Applies if the tree or the panel is active.) Toggles between the tree and
the panel.
F8 (Applies if the tree or the panel is active.) Allows you to gain control of
the split between the tree and 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
tree, increase the width of the panel).
v Press the right arrow key to move the split right (increase the width of
the tree, decrease the width of the 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.
Shift+Tab
If the cursor is on a field in the panel other than the first field, moves
backwards through the fields. Otherwise, toggles between the tree and the
panel.
Space
1. Activates a button.
2. Selects a checkbox.
3. Selects a node in the tree.
Tab
Cycles through the tree, fields in the panel, and the buttons.
Accessibility 273

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Customizing colors and fonts
Use the Settings option on the menu to change colors and fonts. Settings are
not applied consistently on the Task Guide.
To make them more noticeable, the names of items that contain errors are
displayed in the original typeface, in red and underlined.
Using help
Screen readers read the entire page in the help window, rather than the area
required by a user who has pressed F1. Also, the help window is not
navigable by the keyboard. The solution is to open the help files, which are
html files, in a browser outside the configuration tool. The help file index is
cclhlp15.htm in directory:
\bin\resource\
where represents the directory containing the help files in these
languages:
Language
English html
German html_de
Spanish html_es
French html_fr
Italian html_it
Japanese html_ja
Korean html_ko
Turkish html_tr
Simplified Chinese html_zh
Task Guide
Screenreaders cannot read the Task Guide; do not use the Task Guide if you
use a screenreader. Use the menu in the configuration tool to add servers
(Tools —> New server). Use the tree structure to enable protocols that the
Java gateway will use.
274 CICS Transaction Gateway: Windows 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.
A
abend. The termination of a task, job, or
subsystem because of an error condition that
recovery facilities cannot resolve.
APAR. (Authorized program analysis report.) A
report on the basis of which IBM supplies a fix
of a temporary corrective nature to elements of
function SYSMODs. APAR fixes are called
″corrective″ service because they are installed to
cure problems currently being experienced by an
installation. The APAR fix is usually in the form
of either a modification to a load module or an
update to card-image data. It is intended as a
temporary arrangement until a preventive service
(PTF) is issued to fix the problem permanently.
This PTF supersedes the APAR fix, and indeed
specifies this relationship on its ++VER
statement.
API. Application programming interface.
APING. A command used to verify an APPC
link.
APPC. Advanced program-to-program
communication. 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.
applet. A Java program that is downloaded to,
and executed on, a Web browser or network
computer. See also servlet.
applid. In CICS, a system initialization and
terminal control parameter that identifies the
CICS system to other remote systems.
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 facility that enables terminal
definitions to be created automatically in a CICS
server on request. The definition is deleted when
the client terminal is logged off.
automatic transaction initiation (ATI). The
process whereby a transaction request made
internally within a CICS system or network leads
to the scheduling of the transaction. An ATI
request from a CICS Transaction Gateway can
cause the initiation of a transaction in a CICS
server system.
B
beans. See JavaBeans.
BIND. 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.
C
CA. See certification authority.
CEDA. A CICS transaction that defines
resources online.
© Copyright IBM Corp. 1996, 2002 275

Glossary
certification authority. In computer security, an
organization that issues certificates. The
certification 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 External Call Interface (EXCI). An
application programming interface that enables a
program running on Z/OS, such as CICS
Transaction Gateway, to call a program running
in a CICS region. The programs can transfer data
between each other using a communication area.
Compare with External Call Interface (ECI).
CICS Gateway for Java. In CICS Universal
Clients Version 2, an interface between a Java
program and CICS that allows a Java-enabled
browser to dynamically download a Java Applet
and transparently access CICS data. This has
been replaced by the CICS Transaction Gateway.
CICS on open systems. A term used to refer
generically to the products: CICS for HP-UX,
CICS for Sun Solaris, TXSeries for AIX, TXSeries
for HP-UX, and TXSeries for Solaris.
CICS on System/390. A term used to refer
generically to the products CICS Transaction
Server for z/OS , CICS for MVS/ESA, CICS
Transaction Server for z/OS, CICS Transaction
Server for VSE/ESA, and CICS/VSE ® .
cicscli. A command that starts and stops the
Client daemon, checks the availability of servers,
and sets other options.
cicsprnt. A command that allows you to define
a printer terminal on the Client daemon
workstation. The command enables CICS
applications running on the server to direct
output to the client-attached printer.
cicsterm. A command that provides 3270
emulation and enables connection to a CICS
region.
276 CICS Transaction Gateway: Windows Administration
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. An environment variable that tells
the JVM and other Java applications where to
find the class libraries, including user-defined
class libraries.
Client API. On distributed platforms running
non-Java applications, the interface between the
Client application and the Client daemon.
client application. A user application, written in
a supported programming language other than
Java, that communicates directly with the Client
daemon.
Client daemon. The Client daemon (process
cclclnt) exists only on distributed platforms. 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. A distributed application design
model, in which the client sends a request to its
partner, the server, which executes the request
and returns the results to the client. This design
model is associated typically with cooperative
processing.
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. File CICSCOL.INI used by
the CICS Transaction Gateway to customize the
3270 screen color attributes on client
workstations.
COMMAREA. A communication area that is
used for passing data both between programs
within a transaction and between transactions.

Common Object Request Broker Architecture
(CORBA). An industry standard for an interface
definition language that enables different object
request brokers to interoperate.
configuration file. The file CTG.INI containing
information telling CICS Transaction Gateway
about the CICS servers that it can connect to, and
the communication protocols to use.
configuration tool. A graphical user interface
that allows you to configure the CICS
Transaction Gateway.
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.
control table. In CICS, a storage area used to
describe or define the configuration or operation
of the system.
conversation. The communication between a
CICS Transaction Gateway and a CICS server. In
APPC, a connection between two transaction
programs over an LU-LU session that allows
them to communicate with each other while
processing a transaction. See also session.
conversation security. In APPC, a process that
allows validation of a user ID or group ID and
password before establishing a connection.
cooperative processing. A subset of distributed
processing, in which at least the user interface
(presentation) aspect of the application runs on a
programmable workstation.
CORBA. See Common Object Request Broker
Architecture.
ctgstart. A command that starts the gateway
daemon.
D
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.
Glossary
dependent LU. A logical unit (LU) that can
receive, but not send a BIND, and which
supports only single sessions. See BIND.
digital certificate. A form of personal
identification that can be verified electronically.
Only the certificate owner who holds the
corresponding private key can present a
certificate for authentication through a Web
browser session. Anyone can verify that the
certificate is valid by using a readily available
public key.
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. A link that enables
an application program running on one CICS
system to link to another application program
running in another CICS system.
Glossary 277

Glossary
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.
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.
E
EBCDIC. Extended binary-coded decimal
interchange code. A coded character set of 256
8-bit characters developed for the representation
of textual data.
ECI. See external call interface.
emulator, 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. In the CICS Transaction
Gateway the terminal emulation function allows
client workstations to run CICS transactions that
use 3270 data flows.
278 CICS Transaction Gateway: Windows Administration
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.
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 10–megabit or 100–megabit
baseband 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 CICS External Call Interface.
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.
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.
F
firewall. A configuration of software that
prevents unauthorized traffic between a trusted
network and an untrusted network.

G
gateway. A device that connects two dissimilar
LANs, or that connects a LAN to a wide area
network (WAN), midrange computer, or
mainframe computer. A gateway device has its
own processor and memory and may perform
protocol conversion. A gateway handles multiple
communication sessions simultaneously.
gateway classes. The interface for Java Client
applications to connect to the Gateway daemon.
The Gateway classes, which are supplied with
the CICS Transaction Gateway, must be in the
classpath for Java Client applications to run.
gateway daemon. Used only in remote mode,
the Gateway daemon listens on protocols defined
in CTG.INI for gateway requests from remote
Java client applications. It issues these requests to
the Client daemon on distributed platforms, and
directly to CICS over the EXCI on z/OS. The
Gateway daemon runs the protocol listener
threads, the worker threads and the connection
manager threads. It uses the GATEWAY section
of CTG.INI (and on z/OS the ctgenvvar script)
for its configuration.
H
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 in an internet.
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
domain name of a host.
HTTP. In the Internet suite of protocols, the
protocol that is used to transfer and display
hypertext and XML documents.
HTTPS. A TCP/IP protocol that World Wide
Web servers and Web browsers use to transfer
and display documents secured by SSL.
I
iKeyman. A tool supplied with the Gateway for
maintaining digital certificates for SSLight and
JSSE.
independent LU. A logical unit (LU) that can
both send and receive a BIND, and which
supports single, parallel, and multiple sessions.
See BIND.
internet. A collection of networks
interconnected by a set of routers that allow
them to function as a single, large network.
Contrast with Internet.
Internet. The internet administered by the
Internet Architecture Board (IAB), consisting of
large national backbone networks and many
regional and campus networks all over the
world. The Internet uses the Internet suite of
protocols.
Internet address. See IP address.
Glossary
Internet Architecture Board. The technical body
that oversees the development of the internet
suite of protocols known as TCP/IP.
Internet Packet Exchange (IPX). In Novell
NetWare LANs, a communication protocol that
sends data packets to requested destinations.
Internet Protocol (IP). In TCP/IP, a protocol
that routes data from its source to its destination
in an Internet environment.
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.
intranet. A private network that integrates
Internet standards and applications (such as Web
browsers) with an organization’s existing
Glossary 279

Glossary
computer networking infrastructure. Compare
with Internet and internet.
IP. Internet Protocol.
IPX. Internet Packet Exchange.
J
J2EE. (Java 2 Platform, Enterprise Edition.) 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.
Java. An object-oriented programming language
for portable interpretive code that supports
interaction among remote objects.
JavaBeans. A platform-independent, software
component technology for building reusable Java
components called beans. Once built, these beans
can be made available for use by other software
engineers or they can be used in Java
applications. Also, using JavaBeans, software
engineers can manipulate and assemble beans in
a graphical drag-and-drop development
environment.
Java client application. A Java application,
servlet or applet that communicates with the
Gateway classes.
Java development kit (JDK). A software
package that can be used to write, compile,
debug, and run Java applets and applications.
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 Secure Socket Extension (JSSE). An
implementation of SSL, written in Java, and
supported by CICS Transaction Gateway.
280 CICS Transaction Gateway: Windows Administration
Java Virtual Machine (JVM). A software
implementation of a processor that runs
compiled Java code (applets and applications).
JDK. See Java development kit (JDK).
JNI. See Java Native Interface (JNI).
JSSE. See Java Secure Socket Extension (JSSE).
JVM. See Java Virtual Machine (JVM).
K
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. The default keyboard mapping file for
the CICS Transaction Gateway is CICSKEY.INI.
KeyRing or KeyStore. In computer security, a
file that contains public keys, private keys,
trusted roots, and certificates.
L
LAN. See local area network.
local area network (LAN). A network of
workstations, or terminals, or both, where all the
connected systems are relatively near to each
other. See wide area network.
local mode. Describes a Java Client application
using the Gateway local protocol. The Gateway
daemon is not used in local mode; on distributed
platforms, the Gateway classes interface directly
with the Client daemon API, and with the EXCI
on z/OS. See remote mode.
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.
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.
LU-LU session type 6.2. In SNA, a type of
session for communication between peer
systems. Synonymous with APPC protocol.
LU 6.2. See APPC.
M
MAC. Medium access control.
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.
N
name server. In TCP/IP, synonym for Domain
Name Server In Internet communications, the
host that translates host names into their
respective internet addresses when requested by
the hosts on the network A physical device, and
its associated software, that enables a processor
or controller to be connected to a network.
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.
O
object. In object-oriented programming, a
concrete realization of a class that consists of
data and the operations associated with that
data.
object request broker (ORB). Software that
serves as an intermediary by transparently
enabling objects to exchange requests and
responses.
OO. Object-oriented.
P
Glossary
pacing. A technique by which a receiving
station controls the rate of transmission of a
sending station to prevent overrun.
packet internet groper (PING). In Internet
communications, a program used in TCP/IP
networks to test the ability to reach destinations
Glossary 281

Glossary
by sending the destinations an Internet Control
Message Protocol (ICMP) echo request and
waiting for a reply.
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. Packet internet groper. The command
that sends an ICMP Echo Request packet to a
gateway, router, or host with the expectation of
receiving 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. Primary logical unit. 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.
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 (LU) that contains the primary half-session
for a particular LU-LU session. Contrast with
secondary logical unit. See also logical unit.
Note: A particular logical unit may contain
primary and secondary half-sessions for
different active LU-LU sessions.
protocol boundary. The signals and rules
governing interactions between two components
within a node.
282 CICS Transaction Gateway: Windows Administration
R
RACF. Resource Access Control Facility. An IBM
licensed program that provides access control by
identifying users to the system; verifying users of
the system; authorizing access to protected
resources; logging detected, unauthorized
attempts to enter the system; and logging
detected accesses to protected resources.
region. A physical instance of a CICS server.
remote mode. Describes a Java Client
application using a Gateway network protocol to
connect to the Gateway daemon. See local mode.
remote procedure call (RPC). Remote procedure
calls are analogous to the standard procedure
calls used in modern programming, providing
modularity and reducing code size. The main
difference between standard procedure calls and
remote procedure calls is that in a remote
procedure call, the called procedure is being
executed by a different process than the caller. To
the calling procedure, a remote procedure call
looks the same as a call to a local procedure.
When a program makes a remote procedure call
to a remote application, the procedure’s
parameters are automatically bundled into a
request message, which is then sent to the
remote program or system.
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.
RU. Request unit. Response unit.

RPC. See remote procedure call.
S
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.
servlet. A Java servlets program that run on a
Web server machine, unlike Java applets, which
are downloaded to a Web browser. Java servlets
have become popular as a replacement for CGI
(Common Gateway Interface) programs.
session. In SNA, a logical connection between
two network addressable units (NAUs) that can
be activated, tailored to provide various
protocols, and deactivated as requested. The
session activation request and response can
determine options for such things as rate and
concurrency of data exchange, control of
contention and error recovery, and characteristics
of the data stream. Sessions compete for network
resources, such as links within the path control
network. For routing purposes, each session is
identified by the network or local addresses of
the session partners. See LU-LU session, LU-LU
session type.
session limit. In SNA, the maximum number of
concurrently active LU-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.
signon capable terminal. A signon capable
terminal allows signon transactions, either
CICS-supplied (CESN) or user-written, to be run.
Contrast with signon incapable terminal.
SIT (system initialization table). A table
containing parameters used to start a CICS
control region.
SNA gateway. A gateway that handles multiple
APPC communication sessions simultaneously.
See gateway.
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.
SSL. See Secure Sockets Layer (SSL).
Glossary
SSLight. An implementation of SSL, written in
Java, and supported by CICS Transaction
Gateway.
System Management Interface Tool (SMIT). In
the AIX operating system, a set of menu-driven
services that facilitate the performance of system
tasks such as installation, management,
configuration, and diagnosis.
standard error. In many workstation-based
operating systems, the output stream to which
error messages or diagnostic messages are sent.
subnet. In TCP/IP, a part of a network that is
identified by a portion of the Internet address.
Synonym for subnetwork.
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.
Systems Network Architecture (SNA). The
description of the logical structure, formats,
protocols, and operational sequences for
Glossary 283

Glossary
transmitting information units through, and
controlling the configuration and operation of,
networks.
System SSL. An implementation of SSL,
supported by CICS Transaction Gateway on
z/OS. Written in native code, it supports
hardware encryption technology available to
z/OS, and can be used only for SSL servers on
that operating system.
T
Taskguide. A function of the configuration tool
that provides step-by-step guidance to
configuring your CICS Transaction Gateway. .
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. Transmission Control Protocol/Internet
Protocol.
TCP/IP address. An address that uniquely
identifies a machine on a network. A machine
can have several threads of execution running at
the same time; a TCP/IP port uniquely identifies
a particular thread.
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.
Terminal Servlet. A Java program that allows
you to use a Web browser as an emulator for a
3270 CICS application running on any CICS
server.
thread. A stream of computer instructions that
is in control of a process. A multithread process
begins with one stream of instructions (one
thread) and may later create other instruction
streams to perform tasks.
284 CICS Transaction Gateway: Windows Administration
token ring. A network with a ring topology that
passes tokens from one attaching device to
another; for example, the IBM Token-Ring
network.
trace. A record of data that provides a history of
events that occurred in a system. The process of
recording the sequence in which the statements
in a program are executed and, optionally, are
the values of the program variables used in the
statements.
transaction program. A program that uses the
APPC application program interface (API) to
communicate with a partner application program
in the same node or at a partner node.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A set of communications protocols
that support peer-to-peer connectivity functions
for both local and wide area networks. TCP/IP
can be used for client/server links between the
Client daemon and, for example, CICS for OS/2,
CICS for Windows NT.
type 2.0 node. An SNA node that attaches to a
subarea network as a peripheral node and
provides full 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.
U
URL. (Uniform Resource Locator.) 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.
user session. Any APPC session other than a
SNASVCMG session.

V
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.
W
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.
Glossary
Glossary 285

Glossary
286 CICS Transaction Gateway: Windows Administration

Index
Special characters
xii
CICSCLI.BIN 219, 220, 222
CICSCLI.LOG 74
CICSCLI.TRC 219
Numerics
3270 data streams 167, 174
A
accessibility 271
Acrobat 25, 263
adapters 22, 258
administration 149
Adobe 25, 263
advanced program-to-program communication
(APPC) 26, 45
Anynet domain name suffix configuration setting 82
APAR (authorized program analysis report)
authorization 239
closing 240
documentation needed 237
process 240
submitting 239
API (Application Programming Interface) 3
APPC (advanced program-to-program
communication) 26, 45
application development tools 25, 262
Application Programming Interface (API) 3
application servers 24, 261
application tracing 210
Applid configuration setting 71
asymmetric keys 7
ATI 229
authentication 10
Authorized Hosts configuration setting 69
B
beans, Java 14
Biasing configuration setting 85
binary trace formatter 222
BMS Map Conversion Utility 194, 205
books 265
CICS Transaction Gateway 265
browsers 22, 259
bthdinst 77
C
CA (certification authority) 8
CCLCLNT.EXE 230
CCLLOG.HLP 218
cclmeci.dll 184
cclmepi.dll 185
CCLMSG.HLP 218
CCLSNWTP.EXE 230
certification authority (CA) 8
cfwk.zip 215
CICS Gateway for Java 244
CICS gateway for Lotus Notes; 248
CICS resource adapters 90
CICS server problem determination 232
CICS server PTF requirements 25
CICS servers 23, 261
CICS servers, communicating with 41
CICS Transaction Gateway
CICS gateway for Lotus Notes; 248
hardware requirements 22
local 101
migration 241
problem determination 207
starting CICS Transaction Gateway with preset
options 142
starting Gateway with user-specified options 142
startup options 142
stopping 144
Workload management 19
CICS Transaction GatewayStart Menu shortcuts 144
CICSCLI command 156
CICSCLI environment variable 54, 242
cicscli.log 218
CICSCOL environment variable 100
cicseci.rar 90
cicsepi.rar 90
CICSFTRC utility 222
CICSKEY environment variable 97
CICSPRNT command 173
CICSTERM command 167
CICSTERM.INI 172
CLASSPATH 53, 248
CLASSPATH environment variable 124, 215, 216
CLASSPATH setting 53
client control 5
Client daemon
running as a Windows service 153
trace analysis 225
Client daemon tracing 220
© Copyright IBM Corp. 1996, 2002 287

Client daemon, restarting 158
Client daemon, starting 156, 157
Client daemon, stopping 157
client security 158
client trace file 225
Client trace file configuration setting 89
client tracing 158
client/server connections 27
ClientSecurity 91, 93
code pages 28
Codepage identifier override configuration setting 74
codepage problems 213
color mapping file 99, 168
commands
CICSCLI 156
CICSPRNT 173
CICSTERM 167
Common Client Interface (CCI) 16
Common Object Request Broker (CORBA)
standard 19
Communicating with CICS servers 41
communication
problems 233
communication protocols 24, 261
APPC 26
TCP/IP 26
Communications Server 235
compilers 25, 262
configuration
CLASSPATH 53
configuration file 54
configuration tool 54
Gateway.properties file 54
programming environment 53
setting the time 53
configuration conversion tool 241
configuration file 54
referencing 54
renaming 96
configuration file, referencing 165
configuration settings
Anynet domain name suffix 82
Applid 71
Authorized Hosts 69
Biasing 85
Client trace file 89
Codepage identifier override 74
Connection timeout 79
Connection timeout (ms) 63
Description 76
Display TCP/IP hostnames 60
Drop working connections 63
Enable popups 75
Enable protocol handler 62
Enable reading input from console 60
288 CICS Transaction Gateway: Windows Administration
configuration settings (continued)
Enable the Workload Manager 84
Fully qualified CP name or template 82
Gateway trace file 88
Gateway trace wrap size 89
Handler wakeup timeout (ms) 63
Hostname or IP address 78
Idle timeout (ms) 63
Initial number of Connection Manager threads 59
Initial number of Worker threads 59
Initial transaction 77
IP address mask for CP name (optional) 82
IP address mask for LU name template
(optional) 81
Java clients obtaining generic ECI replies 60
KeyRing or Keystore name 66
KeyRing or Keystore password 66
Local LU name 79
Local LU name or template 80
Log client connections and disconnections 61
Log file 74
Manage workload for this program 86
Max dedicated connections 69
Maximum buffer size 72
Maximum Client wrap size 89
Maximum logical SNA sessions 83
Maximum number of Connection Manager
threads 59
Maximum number of Worker threads 59
Maximum requests 72
Maximum servers 72
Maximum SNA RU size 83
Mode name 79, 81
Model terminal definition 77
Named pipe name 84
Partner LU name 79, 80
Ping time frequency (ms) 63
Port 62, 78
Print command 73
Print file 73
Region timeout (s) 85
Remote node inactivity poll interval 83
Require clients to use security classes 64
Round robin 84
Send TCP/IP Keepalive packets 79
Server name 76
Server retry interval 74
SNA pacing size 83
SO_LINGER setting 64
Terminal exit 72
Timeout for in-progress requests to complete
(ms) 61
Trace 86
Trace settings 219
Use client authentication 65

configuration settings (continued)
Use LU alias names 79
Use OEM codepage 75
Use upper case security 78
Use Windows credentials for security 77
Validate message qualifiers 61
Validate Units of Work 60
Worker thread available timeout (ms) 61
configuration tool 54
configuration tool help 274
connecting to CICS servers 157, 161
Connection timeout (ms) configuration setting 63
Connection timeout configuration setting 79
ConnectionURL 91, 92
CORBA (Common Object Request Broker) standard 19
Corrective Service Diskette (CSD) 240
corrective service software 39
CRSR transaction 45
CSD (Corrective Service Diskette) 240
CTG_JNI_TRACE 87, 211
ctgcfg command 54
ctgclient.jar 216
ctgconv, conversion tool 242
ctgikey 104, 115
ctgjava 147
ctgjava command 52
ctgsamples.jar 248
ctgserver.jar 216
ctgservice utility 147
ctgstart command 142
customizing
keyboard 97
screen colors 99
D
Data conversion 50
defining 3270 printer terminal emulator
characteristics 174
defining 3270 terminal emulator characteristics 168
Description configuration setting 76
development tools 25, 262
DeviceType 94
diagnosing common problems
Client daemon 227
codepage problems 213
Gateway daemon 212
if a process locks 213
Java exceptions 216
Java security exceptions 217
java.lang.OutOfMemory exception 217
running as a windows service 213
SSL exceptions 214
using Java debugging tools to debug user
applications 218
diagnostic tools
APING 234
digital certificates 8, 10
externally signed 105, 115
maintaining 104, 115
self-signed 110, 120
digital signatures 8
disability 271
disabling the display of messages 159
disabling the display of pop-up messages 159
disk space required 22, 258
Display TCP/IP hostnames configuration setting 60
displaying command syntax 160
distinguished name (DN) 8
DN (distinguished name) 8
documentation 265
documenting problems 237
Drop working connections configuration setting 63
dynamic name generation (TCP62) 82
E
ECI (External Call Interface) 1, 3, 4
ECI resource adapter 91
Enable popups configuration setting 75
Enable protocol handler configuration setting 62
Enable reading input from console configuration
setting 60
Enable the Workload Manager configuration
setting 84
enabling the display of pop-up messages 159
Encoding 94
encryption 7, 10
eNetwork Communications Server 46
Enterprise Information Systems (EIS) 15
environment variables 96
CICSCLI 54, 242
CICSCOL 100
CICSKEY 97
CLASSPATH 53, 124, 215
CTG_JNI_TRACE 87, 211
JAVA_HOME 104, 115
PATH 36, 102
EPI (External Presentation Interface) 1, 3, 4
EPI resource adapter 92
EPIBasicScreenHandler 248
EPIMonitor 248
EPIScreenButtons 248
error log
cicscli.log 218
client error log 218
server error log 233
Error log
IBM Communications Server 235
ESI (External Security Interface) 1, 3, 4
Euro support 74, 75
Index 289

EXEC CICS RETURN TRANSID IMMEDIATE
command 169, 175
External Call Interface (ECI) 1, 3, 4
External Presentation Interface (EPI) 1, 3, 4
External Security Interface (ESI) 1, 3, 4
externally-signed certificates 9
F
firewalls 14
font selection on terminal emulators 172
fonts
selecting on terminal emulators 172
free memory 72
Fully qualified CP name or template configuration
setting 82
G
Gateway daemon tracing 209
Gateway trace file configuration setting 88
Gateway trace wrap size 89
Gateway.properties file 54
generic ECI replies
Configuration 60
Getsense 235
GhostView 25, 263
glossary of terms and abbreviations 275
H
Handler wakeup timeout (ms) configuration
setting 63
hangs 213, 232
hardware requirements 22
help 274
Hostname or IP address configuration setting 78
HTTP (Hypertext Transfer Protocol) 2
HTTP over SSL (HTTPS) 2
HTTPS 12
HTTPS (HTTP over SSL) 2
Hypertext Transfer Protocol (HTTP) 2
I
IBM Communicatins Server 235
Idle timeout (ms) configuration setting 63
IIOP (Internet InterOrb Protocol) 19
iKeyMan 104, 115
distributing to client workstations 104
inactivity poll interval 45
Initial number of Connection Manager threads
configuration setting 59
Initial number of Worker threads configuration
setting 59
initial transaction 168, 174
Initial transaction configuration setting 77
initialization files
cicscol.ini 99, 100
cicskey.ini 97
290 CICS Transaction Gateway: Windows Administration
initialization files (continued)
CICSTERM.INI 172, 243
install_path xii
installation
CICS Transaction Gateway 29
complete installation 29
custom installation 29
maintaining CICS Transaction Gateway 37
path xii
problems 30, 37
repairing CICS Transaction Gateway 37
silent installation 39
types of installation 29
uninstalling CICS Transaction Gateway 37
installation path xii
InstallTimeout 94
Internet InterOrb Protocol (IIOP) 19
IP address mask for CP name (optional) configuration
setting 82
IP address mask for LU name template (optional)
configuration setting 81
J
J2EE
resource adapter files 90
resource adapters 3
Java
applet 13
application 13
beans 14
classes 3
firewall 14
Java language 12
samples 248
servlet 13
Java debugging tools, using 218
Java development kit 23, 260
Java exceptions 213, 216
Java Secure Socket Extension (JSSE) 23, 260
Java security exceptions 217
Java virtual machine (JVM) 52
JAVA_HOME environment variable 104, 115
java.lang.OutOfMemory exception 217
JDK levels 23, 260
JNI tracing 87, 149, 211
JSSE 9, 11, 23, 114, 115, 260
installation 114
migration from SSLight 114
JVM (Java virtual machine) 52
K
KeepAlive packets 45
keyboard 272
keyboard mapping file 97, 168
KeyRing or Keystore name configuration setting 66

KeyRing or Keystore password configuration
setting 66
KeyRingClass 92, 94
KeyRingPassword 92, 94
KeyRings 9, 104
keys specific to particular keyboards 99
KeyStores 9, 115
L
license files 32
listing connected servers 159
local CICS Transaction Gateway 101
local gateway connection 13
Local LU name configuration setting 79
Local LU name or template configuration setting 80
Local Named Pipe protocol 26
locks 213
Log file configuration setting 74
logical unit (LU) 45
LogonLogoffClass 94
LU6.2 26
M
Manage workload for this program configuration
setting 86
mapping files
renaming 96
Max dedicated connections configuration setting 69
Maximum buffer size configuration setting 72
Maximum Client wrap size configuration setting 89
Maximum logical SNA sessions configuration
setting 83
Maximum number of Connection Manager threads
configuration setting 59
Maximum number of Worker threads configuration
setting 59
Maximum requests configuration setting 72
Maximum servers configuration setting 72
Maximum SNA RU size configuration setting 83
memory leak 217
memory requirements 72
messages 208, 218
messages, disabling the display of 159
Microsoft SNA Server 49
migrating from CICS Gateway for Java 244
migration
CICS Client Version 2 243
CICS Gateway for Java 244
CICS Universal Client Version 3.0 243
configuration files 243
migration issues 241
mode definitions, APPC 45
Mode name configuration setting 79, 81
Model terminal definition configuration setting 77
N
Named pipe name configuration setting 84
Named Pipes protocol 50
network drives, problems with 36
network gateway connection 13
Network Provider Interface (NPI) 126
network security
authentication 10
certification authority (CA) 8
concepts 6
ctgikey 104, 115
digital certificates 8, 10
externally signed 105, 115
maintaining 104, 115
self-signed 110, 120
digital signatures 8
distinguished name (DN) 8
encryption 7, 10
externally-signed certificates 9
HTTPS 12, 124
iKeyMan 104, 115
distributing to client workstations 104
JSSE 9, 11, 114, 115
installation 114
migration from SSLight 114
KeyRings 9, 104
keys 7
KeyStores 9, 115
migrating old self-signed certificates 114, 124
Network Provider Interface (NPI) 126
security exits 12
self-signed certificates 9
signer certificate 8
SSL 10, 124
SSL handshaking 10
SSLight 11, 104
System SSL 11
trusted root key 8
X.509 protocol 8, 10
non-existent directories 36
NPI (Network Provider Interface) 126
O
object request broker (ORB) 19
online help, for end user messages, 218
onlne help, for trace and log messages 218
operating systems 22, 258
operation
starting the Gateway 141
stopping the Gateway 144
options
CICSCLI command 160
CICSPRNT command 176
CICSTERM command 170
ORB (object request broker) 19
Index 291

P
Partner LU name configuration setting 79, 80
Password 91, 93
password expiry management (PEM) 4, 130
PATH environment variable 36
PEM (password expiry management) 4, 130
performance
assessing 135
CICS Transaction Gateway configuration 136
Java considerations 138
monitoring 140
other system factors 138
tracing 139
Ping time frequency (ms) configuration setting 63
planning 21
PMR (Problem Management Record) 236
pop-up messages, disabling the display of 159
pop-up messages, enabling the display of 159
Port configuration setting 62, 78
PortNumber 91, 93
Print command configuration setting 73
Print file configuration setting 73
print file, processing 168, 174
print terminal emulator, starting 174
printer support 5
printer terminal emulator characteristics, defining 174
problem determination 207
application tracing 210
diagnosing common problems
Gateway daemon 212
Gateway daemon tracing 209
JNI tracing 211
messages 208, 218
preliminary checks 207
servlet tracing and logging in WebSphere 211
tracing
Client daemon 219
Gateway daemon 209
Problem Management Record (PMR) 236
problem reporting
documenting problems 237
information needed 238
support organization 236
problems, communication 233
process locks 213
program support 236
protocols
HTML 16
HTTP 2
HTTPS 2
SSL 2, 10
TCP/IP 2
PTF (Program Temporary Fix) 240
public key encryption 7
publications, CICS Transaction Gateway 265
292 CICS Transaction Gateway: Windows Administration
R
railroad diagrams xii
re-authentication support 92, 95
README file 21
ReadTimeout 94
Region timeout (s) configuration setting 85
Remote Method Invocation (RMI) 19
Remote node inactivity poll interval 45
Remote node inactivity poll interval configuration
setting 83
removing CICS Transaction Gateway 37
Require clients to use security classes configuration
setting 64
requirements, hardware 22
resource adapter files 90
resource adapters 90
resource adapters, J2EE 3
Restarting the Client daemon 158
restrictions, using CICS servers 27
RETAIN database 236
RETAIN problem management system
APARs 240
Problem Management Record 236
RMI (Remote Method Invocation) 19
roaming user support 172
Round robin configuration setting 84
S
samples text file 195
samples, Java 248
Samples.txt 195, 196
screen readers 25, 263
Secure Sockets Layer (SSL) 2, 10
security 78
External Security Interface (ESI) 4
password expiry management (PEM) 4
security exits 12
self-signed certificates 9
Send TCP/IP Keepalive packets configuration
setting 79
Sense codes 235
Server name configuration setting 76
Server retry interval configuration setting 74
ServerName 91, 93
servers
application 24, 261
CICS 23, 261
web 24, 261
servers, listing 159
ServerSecurity 92, 93
Service startup parameters 155
services, Windows 146, 153
services, Windows NT 146
servlet tracing and logging in WebSphere 211
servlets 13

shortcut keys 272
signer certificate 8
signon capable terminals 25
SignonType 94
silent installation 39
SNA 24, 261
checking configuration 234
configuring 45
SNA (Systems Network Architecture) 26
SNA pacing size configuration setting 83
SNA Server 49
SO_LINGER setting configuration setting 64
SSL (Secure Sockets Layer) 2, 10
SSL exceptions 214
SSL handshaking 10
SSLight 11, 104
Start Menu shortcuts, creating 36
Start Menu shortcuts, for Client daemon
commands 36
starting a 3270 print terminal emulator 174
starting a 3270 terminal emulator 168
starting CICS Transaction Gateway 141
Starting the Client daemon 156, 157
Starting the Client daemon service at Windows NT
startup 155
Startup options for the CICS Transaction Gateway
service 146
stopping a terminal emulator 169
Stopping the Client daemon 157
stopping the Gateway 144
support organization
program support 236
sending documentation to 239
symmetric keys 7
syntax notation xii
System SSL 11
Systems Network Architecture (SNA) 26
T
TCP/IP (Transmission Control Protocol/Internet
Protocol) 2, 24, 26, 41, 262
TCP/IP communication problems 228
TCP62 24, 262
communication problems 230
multiple server definitions 243
port number 83
TCP62 protocol 42
TCP62 support 28
TCPAdmin protocol settings 69
Telnet 23, 260
terminal emulation 4
terminal emulator
preferences 172
terminal emulator characteristics, defining 168
terminal emulator, starting 168
terminal emulator, stopping 169
Terminal exit configuration setting 72
Terminal Servlet 4
the system locks up 232
thread limits 17
timeout 94
Timeout for in-progress requests to complete (ms)
configuration setting 61
tools
application development 25, 262
other 25, 263
TPNName 91
Trace configuration setting 86
Trace settings, configuration tool 219
TraceLevel 92, 95
tracing 95
Client daemon 219
dynamic 149
Gateway daemon 149, 209
if the Gateway daemon is running as a Windows
service 210
JNI 149
levels 95
performance considerations 210
query current trace settings 149
tracing, JNI 211
TranName 91
transaction programs (TP), APPC 45
transaction support 92, 95
transmission control protocol/internet protocol
(TCP/IP) 26
Transmission Control Protocol/Internet Protocol
(TCP/IP) 2, 26, 41
traps 230
troubleshooting
hangs 232
starting clients and terminals 228
traps 230
trusted root key 8
U
uninstall 37
updating
installed software 39
Use client authentication configuration setting 65
Use LU alias names configuration setting 79
Use OEM codepage configuration setting 75
Use upper case security configuration setting 78
Use Windows credentials for security configuration
setting 77
Userid 91, 93
V
Validate message qualifiers 61
Validate Units of Work 60
Index 293

variables, environment 96
VTAM
buffer trace 234
W
web browsers 22, 259
web servers 24, 261
Web servers 15
Windows NT service 146
Windows secured environment 75
Windows service 146, 153
WINSOCK 229
Worker thread available timeout (ms) configuration
setting 61
Workload management 19
Workload Manager 56, 84
biasing algorithm 183
installation 185
overview 179
port 180
programs 180
regions 180
round-robin algorithm 183
server instance 180
TCP/IP port 180
workload management 180
X
X.509 protocol 8, 10
XAResource 92
294 CICS Transaction Gateway: Windows Administration

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.
© Copyright IBM Corp. 1996, 2002 295

Trademarks
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 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
CICS eNetwork
IBM MQSeries
MVS MVS/ESA
OS/390 OS/400
RETAIN TXSeries
VisualAge VSE/ESA
VTAM WebSphere
296 CICS Transaction Gateway: Windows Administration

Lotus Domino, Lotus Notes, and Domino Go Webserver are trademarks of
Lotus Development Corporation.
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 in the United States and other countries
licensed exclusively through X/Open Company Limited.
Other company, product or service names may be trademarks or service
marks of others.
Notices 297

298 CICS Transaction Gateway: Windows 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, 2002 299

����
Program Number: 5724-D12
Printed in U.S.A.
SC34-6190-00

Spine information:
��� CICS Transaction Gateway Windows Administration Version 5.0

CICS Transaction Gateway
UNIX Administration
Version 5.0
���
SC34-6139-00

CICS Transaction Gateway
UNIX Administration
Version 5.0
���
SC34-6139-00

Note!
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page 265.
First Edition (July 2002)
This edition applies to Version 5.0 of the CICS ® Transaction Gateway, program number 5724-D12. It will also apply to
all subsequent versions, releases, and modifications until otherwise indicated in new editions.
Vertical lines at the left side of the page indicate material that is new to this edition.
© Copyright International Business Machines Corporation 1996, 2002. 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
Conventions and terminology used in this
book . . . . . . . . . . . . . . viii
Installation path . . . . . . . . . . x
Programming language specific . . . . . x
Operating system specific . . . . . . . x
Syntax notation . . . . . . . . . . x
Summary of changes . . . . . . . . xiii
Chapter 1. Overview . . . . . . . . . 1
What CICS Transaction Gateway provides . . 3
A Gateway daemon. . . . . . . . . 3
The Gateway classes . . . . . . . . 3
J2EE resource adapters . . . . . . . . 3
A Client daemon . . . . . . . . . . 3
The external access interfaces (ECI, EPI, ESI) 3
A Terminal Servlet . . . . . . . . . 4
Additional functions . . . . . . . . . 4
3270 terminal emulation (cicsterm) . . . . 4
3270 printer support (cicsprnt) . . . . . 5
CICS Transaction Gateway: local control . . 5
CICS Transaction Gateway: remote control 6
Network security. . . . . . . . . . . 6
Encryption . . . . . . . . . . . . 7
Digital signatures and digital certificates . . 8
Obtaining a digital certificate. . . . . . 9
KeyRings and KeyStores . . . . . . . 9
Authentication using SSL . . . . . . 10
HTTPS . . . . . . . . . . . . . 12
Security exits. . . . . . . . . . . 12
Java technology . . . . . . . . . . . 12
The Java language . . . . . . . . . 12
Java applets . . . . . . . . . . . 13
Java servlets . . . . . . . . . . . 13
Java applications . . . . . . . . . 13
JavaBeans . . . . . . . . . . . 14
Firewalls . . . . . . . . . . . . 14
Web servers . . . . . . . . . . . 15
The J2EE resource adapters . . . . . . . 15
How CICS Transaction Gateway accesses
CICS . . . . . . . . . . . . . . 16
The CICS Transaction Gateway: threading
model . . . . . . . . . . . . . . 17
|
|
|
CICS Transaction Gateway and object request
brokers. . . . . . . . . . . . . . 19
Chapter 2. Planning your installation . . . 21
Hardware requirements . . . . . . . . 22
Supported software . . . . . . . . . 23
Operating systems . . . . . . . . . 23
Web browsers . . . . . . . . . . 23
Telnet clients . . . . . . . . . . . 23
JDK levels. . . . . . . . . . . . 24
JSSE. . . . . . . . . . . . . . 24
CICS Servers. . . . . . . . . . . 24
Web servers . . . . . . . . . . . 25
Application servers . . . . . . . . 25
SNA communications . . . . . . . . 25
TCP/IP communications . . . . . . . 25
TCP62 communications . . . . . . . 25
Compilers and application development
tools . . . . . . . . . . . . . 25
Other tools . . . . . . . . . . . 26
GPL licence and copyright issues on Linux 26
CICS server PTF requirements . . . . . . 26
Terminal Signon capability . . . . . . 26
Timeout support . . . . . . . . . 26
Communication between the Gateway and
CICS servers . . . . . . . . . . . . 27
Restrictions on CICS for OS/400 . . . . 28
Why use a particular protocol?. . . . . 29
DBCS Multibyte Characters . . . . . . . 29
Chapter 3. Installation . . . . . . . . 31
Installing the CICS Transaction Gateway . . 31
National language support . . . . . . . 33
Using an alternative code set on AIX. . . 33
Using an alternative code set (other UNIX
platforms). . . . . . . . . . . . 34
Using X-Windows from a remote system . . 35
Uninstalling the CICS Transaction Gateway 35
Chapter 4. Setting up communication with
CICS servers . . . . . . . . . . . 37
TCP/IP configuration . . . . . . . . . 37
Verifying the TCP/IP installation . . . . 37
Next steps . . . . . . . . . . . 38
TCP62 configuration . . . . . . . . . 38
© Copyright IBM Corp. 1996, 2002 iii

|
|
|
|
|
|
|
On z/OS . . . . . . . . . . . . 40
On CICS Transaction Server for z/OS . . 40
On the workstation . . . . . . . . 41
Firewall implications . . . . . . . . 41
KeepAlive packets . . . . . . . . . 41
Next steps . . . . . . . . . . . 42
SNA configuration (AIX only) . . . . . . 42
Configuring SNA for the CICS Transaction
Gateway for AIX . . . . . . . . . 42
Data conversion. . . . . . . . . . . 44
Configuring message queues . . . . . . 44
Chapter 5. Configuration . . . . . . . 47
Before you start. . . . . . . . . . . 48
Gather information. . . . . . . . . 48
Configure your programming environment 48
Recommended Java options for the Solaris
JVM. . . . . . . . . . . . . . 49
Using the configuration tool . . . . . . 49
Running the configuration tool on a
different operating system . . . . . . 50
The configuration tool interface . . . . 51
Configuring CICS Transaction Gateway
settings . . . . . . . . . . . . 53
Configuring Client settings . . . . . . 66
Configuring Server settings . . . . . . 70
Trace settings . . . . . . . . . . 78
Editing the configuration file . . . . . . 80
J2EE setup and configuration . . . . . . 81
Deploying CICS resource adapters . . . 81
Tracing. . . . . . . . . . . . . 86
Sample configuration and mapping files . . 87
Keyboard mapping for cicsterm . . . . . 88
Keyboard mapping file syntax . . . . . 88
The keyboard mapping file . . . . . . 88
Customizing the screen colors for cicsterm . . 90
Color mapping syntax . . . . . . . 91
The color mapping file . . . . . . . 91
Preparing to use local CICS Transaction
Gateway support . . . . . . . . . . 92
Chapter 6. Network Security . . . . . . 93
Determining your use of SSLight or JSSE for
the SSL and HTTPS protocols . . . . . . 94
SSLight . . . . . . . . . . . . . 94
Conflict with JSSE . . . . . . . . . 94
Maintaining your digital certificates for
SSLight . . . . . . . . . . . . 94
Using externally signed certificates under
SSLight . . . . . . . . . . . . 95
iv CICS Transaction Gateway: UNIX Administration
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under
SSLight . . . . . . . . . . . . 100
Java Secure Socket Extension (JSSE) . . . . 104
Migration from SSLight . . . . . . . 104
Installation . . . . . . . . . . . 104
Maintaining your digital certificates for
JSSE . . . . . . . . . . . . . 105
Using externally signed certificates under
JSSE . . . . . . . . . . . . . 105
Using self-signed certificates under JSSE 110
Configuring CICS Transaction Gateway for
SSL and HTTPS . . . . . . . . . . 114
SSL and HTTPS configuration settings 114
Specifying a client KeyRing or KeyStore 115
Using the SSL and HTTPS protocols . . 115
Chapter 7. Client Security . . . . . . 117
Overview . . . . . . . . . . . . 117
Default connection settings. . . . . . . 118
ECI security. . . . . . . . . . . . 118
EPI terminal security. . . . . . . . . 118
Password expiry management . . . . . 119
Signon capable and signon incapable
terminals. . . . . . . . . . . . . 120
Mainframe CICS servers . . . . . . 121
TXSeries and CICS OS/2 servers. . . . 123
CICS/400 servers . . . . . . . . . 123
Chapter 8. Performance . . . . . . . 125
Assessing system performance . . . . . 125
CICS Transaction Gateway configuration . . 126
Java considerations . . . . . . . . . 128
Other system factors . . . . . . . . . 128
Tracing . . . . . . . . . . . . . 129
Performance monitoring tools. . . . . . 130
Chapter 9. Operating the Gateway . . . 131
Before you start . . . . . . . . . . 131
Starting the Gateway. . . . . . . . . 132
Starting the Gateway with preset options 132
Starting the Gateway with user-specified
options . . . . . . . . . . . . 132
Stopping the Gateway . . . . . . . . 134
Administering your system . . . . . . 135
Setting the Gateway trace . . . . . . 135
Setting the JNI trace . . . . . . . . 135
Querying trace settings . . . . . . . 135
Parameters . . . . . . . . . . . 136
Chapter 10. Operating the Client daemon 139

The cicscli command. . . . . . . . . 139
The cicscli command. . . . . . . . . 139
Starting the Client daemon. . . . . . 140
Starting connections with additional
servers . . . . . . . . . . . . 140
Stopping the Client daemon in a
controlled manner . . . . . . . . 140
Stopping the Client daemon immediately 141
Restarting the Client daemon in a
controlled manner . . . . . . . . 141
Restarting the Client daemon
immediately . . . . . . . . . . 141
Starting client tracing . . . . . . . 142
Specifying the trace components . . . . 142
Stopping client tracing . . . . . . . 142
Security considerations for trace and log
files . . . . . . . . . . . . . 142
Setting up security . . . . . . . . 143
Version information . . . . . . . . 143
Listing the connected servers . . . . . 144
Disabling the display of messages . . . 144
Enabling and disabling the display of
console messages . . . . . . . . . 144
Displaying the command parameters . . 145
The cicscli command and applications 145
cicscli command reference . . . . . . . 145
Chapter 11. Terminal Emulation . . . . 151
Summary of Terminal Emulation commands 151
The cicsterm command . . . . . . . . 151
Using cicsterm . . . . . . . . . . 152
Stopping a terminal emulator . . . . . 153
cicsterm and user exits . . . . . . . 153
cicsterm and RETURN TRANSID
IMMEDIATE . . . . . . . . . . 153
Using X-Windows Clients . . . . . . 153
Using cicsterm with an XTERM window 154
cicsterm command reference . . . . . . 154
The cicsprnt command . . . . . . . . 157
Using cicsprnt . . . . . . . . . . 157
cicsprnt and user exits . . . . . . . 158
cicsprnt and RETURN TRANSID
IMMEDIATE . . . . . . . . . . 158
cicsprnt command reference . . . . . . 158
Chapter 12. The Terminal Servlet program 163
What is the CICS Transaction Gateway
Terminal Servlet? . . . . . . . . . . 163
Installing and configuring the Terminal
Servlet . . . . . . . . . . . . . 165
Configuring the Web server’s
CLASSPATH and PATH settings . . . . 166
Adding the Terminal Servlet to the Web
server’s configuration . . . . . . . 166
Configuring the servlet initialization
parameters . . . . . . . . . . . 166
Considering other configuration options 170
Loading the Terminal Servlet . . . . . 171
Using the Terminal Servlet. . . . . . . 171
Connecting to CICS and starting a
transaction . . . . . . . . . . . 171
Invoking the Terminal Servlet . . . . . 171
What happens next? . . . . . . . . 173
Displaying screens and fields . . . . . 173
Sending the screen back to CICS. . . . 175
Setting the AID . . . . . . . . . 175
Disconnecting . . . . . . . . . . 176
Properties and parameters reference . . . 176
Servlet configuration properties . . . . 177
Page mapping properties . . . . . . 179
Request parameters . . . . . . . . 180
Displayable properties . . . . . . . 181
CICS Transaction Server for z/OS Web
Interface . . . . . . . . . . . . . 182
Chapter 13. Problem determination and
problem solving. . . . . . . . . . 183
Preliminary checks . . . . . . . . . 183
What to do next . . . . . . . . . 184
Problems with the Gateway daemon . . . 184
Messages . . . . . . . . . . . 184
Tracing . . . . . . . . . . . . 185
Diagnosing common problems: Gateway
daemon . . . . . . . . . . . . 188
Problems with the Client daemon . . . . 194
Messages . . . . . . . . . . . 194
Tracing . . . . . . . . . . . . 195
Diagnosing common problems: Client
daemon . . . . . . . . . . . . 203
Program support . . . . . . . . . . 212
Reporting problems . . . . . . . . 212
Documenting problems . . . . . . . 213
Locating and compiling information . . 214
Submitting the documentation . . . . 215
APARs and fixes . . . . . . . . . 215
Chapter 14. Migration . . . . . . . . 217
The configuration conversion tool . . . . 217
Using the conversion tool . . . . . . 218
Contents v

|
|
|
Migrating from CICS Transaction Gateway
Version 4. . . . . . . . . . . . . 218
Migrating from CICS Universal Client, or
CICS Transaction Gateway, Version 3 . . . 219
Migrating from CICS Gateway for Java . . 219
Migrating from the CICS Internet Gateway
on AIX . . . . . . . . . . . . . 220
CICS Internet Gateway default settings 220
CICS Internet Gateway override settings 221
CICS Internet Gateway actions 222
Administration functions . . . . . . 223
Migrating from CICS Gateway for Lotus
Notes . . . . . . . . . . . . . 223
Configuring APPC for CICS Transaction
Gateway for AIX . . . . . . . . . . 224
EPI beans provided in earlier versions of the
CICS Transaction Gateway . . . . . . . 224
Appendix A. Data conversion when using
the Client daemon and a CICS server . . 225
Supported conversions . . . . . . . . 225
Appendix B. Hardware and software. . . 229
Hardware requirements. . . . . . . . 229
Supported software . . . . . . . . . 230
Operating systems . . . . . . . . 230
Web browsers . . . . . . . . . . 231
Telnet clients . . . . . . . . . . 231
JDK levels . . . . . . . . . . . 232
JSSE . . . . . . . . . . . . . 232
CICS Servers . . . . . . . . . . 232
Web servers. . . . . . . . . . . 233
Application servers . . . . . . . . 233
SNA communications . . . . . . . 233
TCP/IP communications . . . . . . 234
TCP62 communications . . . . . . . 234
Compilers and application development
tools . . . . . . . . . . . . . 234
vi CICS Transaction Gateway: UNIX Administration
|
|
|
|
|
|
|
|
|
|
|
Screen readers . . . . . . . . . . 234
Other tools . . . . . . . . . . . 235
GPL licence and copyright issues on
Linux . . . . . . . . . . . . . 235
The product library and related literature 237
CICS Transaction Gateway books . . . . 237
Sample configuration documents. . . . . 238
Redbooks . . . . . . . . . . . . 239
Other Useful Books . . . . . . . . . 239
CICS Transaction Server publications . . 239
APPC-related publications . . . . . . 240
TCP62–related publications . . . . . 240
Obtaining books from IBM. . . . . . . 240
Accessibility . . . . . . . . . . . 241
Documentation . . . . . . . . . . 241
iKeyMan. . . . . . . . . . . . . 241
Samples . . . . . . . . . . . . . 241
Configuration tool accessibility . . . . . 241
Components . . . . . . . . . . 241
Keys . . . . . . . . . . . . . 241
Customizing colors and fonts . . . . . 243
Using help . . . . . . . . . . . 243
Task Guide . . . . . . . . . . . 244
Glossary . . . . . . . . . . . . 245
Index . . . . . . . . . . . . . 257
Notices . . . . . . . . . . . . . 265
Trademarks . . . . . . . . . . . . 266
Sending your comments to IBM . . . . 269

About this book
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.
Summary of changes Read this for information on functional changes made in this
version of CICS Transaction Gateway.
Chapter 1, “Overview” Read this for an overview of CICS Transaction Gateway and
the functions it provides.
Chapter 2, “Planning
your installation”
Chapter 3,
“Installation”
Chapter 4, “Setting up
communication with
CICS servers”
Chapter 5,
“Configuration”
Chapter 6, “Network
Security”
Chapter 7, “Client
Security”
Chapter 8,
“Performance”
Chapter 9, “Operating
the Gateway”
Chapter 10,
“Operating the Client
daemon”
Chapter 12, “The
Terminal Servlet
program”
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 network security protocols SSL and
HTTPS.
Read this for information on how to provide a userid 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 Gateway
daemon.
Read this for information on how to operate the Client
daemon of CICS Transaction Gateway.
Read this for information on how to use the Terminal Servlet
to access CICS 3270 applications using a Web browser.
© Copyright IBM Corp. 1996, 2002 vii

Chapter 13, “Problem
determination and
problem solving”
Chapter 14,
“Migration”
Appendix A, “Data
conversion when
using the Client
daemon and a CICS
server”
The product library
and related literature
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.
Read this for information on the conversion of character data
as it passes between the Client daemon of CICS Transaction
Gateway and a CICS server.
Read this for information on the CICS Transaction Gateway
product library and related literature, and the various forms
in which it is available.
Accessibility Read this for information on the accessibility features of CICS
Transaction Gateway.
Notices Read this for important information on the availability of
IBM products and service in different countries, and also on
issues concerning patents, licenses, and trademarks.
Sending your
comments to IBM
Read this for information on how to send your comments to
IBM.
Conventions and terminology used in this book
A number of parts, both internal and external to the CICS Transaction
Gateway, are used when creating a business solution using the product.
Figure 1 on page ix shows some of the possible scenarios you will encounter,
and the terminology used in each case.
viii CICS Transaction Gateway: UNIX Administration

Distributed platforms running in remote mode
Java client
application
z/OS running in local mode
Java client
application
Gateway
classes
Gateway
classes
CICS
server
Gateway
daemon
Distributed platforms running in local mode
Java client
application
Gateway
classes
Client
daemon
Distributed platforms running non-Java applications
Client
application
Client
daemon
z/OS running in remote mode
Java client
application
Gateway
classes
CICS
server
Gateway
daemon
Client
daemon
CICS
server
CICS
server
Figure 1. CICS Transaction Gateway uses, with their associated terminology
CICS
server
The following explains the terms used in Figure 1:
Gateway daemon
Used only in remote mode, the Gateway daemon listens on protocols
defined in CTG.INI for gateway requests from remote Java client
applications. It issues these requests to the Client daemon on
distributed platforms, and directly to CICS over the EXCI on z/OS ® .
The Gateway daemon runs the protocol listener threads, the worker
threads and the connection manager threads. It uses the GATEWAY
section of CTG.INI (and on z/OS the ctgenvvar script) for its
configuration.
Client daemon
The Client daemon (process cclclnt) exists only on distributed
platforms. 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.
About this book ix

Gateway classes
The interface for Java Client applications to connect to the Gateway
daemon. The Gateway classes, which are supplied with the CICS
Transaction Gateway, must be in the classpath for Java Client
applications to run.
Client application
A user application, written in a supported programming language
other than Java, that communicates directly with the Client daemon.
Java Client application
A Java application, servlet or applet that communicates with the
Gateway classes.
Installation path
The term is used in file paths to represent the directory where
you installed the product. The default installation locations for each operating
system are shown in Table 1:
Table 1. Default CICS Transaction Gateway installation locations
Operating System Default installation location
Windows ®
c:\Program Files\IBM\IBM CICS Transaction Gateway
AIX ®
/usr/lpp/ctg
Linux, HP-UX, Solaris /opt/ctg
z/OS A ctg subdirectory of the directory from which the
installation was run. For example, if the CICS
Transaction Gateway was installed by the command
ctginstall in the /usr/lpp directory, the
is /usr/lpp/ctg
Programming language specific
The term C refers to both the C and C++ programming languages.
Operating system specific
Unless otherwise specified, the term Windows refers to Windows NT ® ,
Windows 2000, and Windows XP.
The term Windows 2000 Terminal Server means a server with the Terminal
Services feature installed.
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.
Syntax notation
The syntax of commands is shown in a standard way. This syntax, commonly
known as railroad syntax, is described in Table 2 on page xi. You interpret the
syntax by following the arrows from left to right, and from top to bottom,
x CICS Transaction Gateway: UNIX Administration

along the main path line.
Table 2. Command syntax conventions
Symbol Meaning
Required items appear on the main path line.
►► AB ►◄
►► A
B
C
►►
►►
►►
A B
A
B
C
A
B
C
►► ▼ A
►► ▼
A
B
C
B
►◄
►◄
►◄
►◄
►◄
►◄
Punctuation and uppercase
characters
Lowercase characters appearing
like this
If there is more than one required item to choose
from, the items are stacked vertically. This is a set of
alternatives—one of which you must specify.
Optional items appear below the main path line.
If there is more than one optional item to choose
from, the items are stacked vertically below the
main path line. This is a set of alternatives—one of
which you may specify.
If one item in a set of alternatives is the default, this
item appears above the main path line and all other
items are stacked vertically below the line.
An arrow returning to the left above items on the
main path line means that the items can be repeated.
Such items may be either required or optional.
An arrow returning to the left above a set of items
means that more than one item can be selected or
that a single item can be repeated.
Note: For CICS, unless otherwise stated, this
representation means only that more than one item
can be selected.
Code exactly as shown.
Code your own text, as appropriate. For example,
with FILE(name) you must specify FILE and ()
unchanged, but are free to specify any valid text
string for the name of your file.
About this book xi

xii CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Summary of changes
The following functional changes have been made for CICS Transaction
Gateway Version 5.0:
v The Binary Trace Formatter utility has been enhanced to format SNA and
MPTN data structures within TCP62 data flows. See “Formatting the binary
trace file” on page 197.
v A systems administration function allows you to set options for Gateway
and JNI traces, to start and stop these traces, and to query trace settings;
see “Administering your system” on page 135. Using the CTG_JNI_TRACE
environment variable to enable JNI tracing is supported only for migration
purposes.
v The way that CICS Transaction Gateway writes log messages has changed:
– Each message entry begins with the current date in the format
month/day/year.
– CICS Transaction Gateway writes error and warning messages to
standard error (stderr), and information messages to standard output
(stdout); see “Messages” on page 184.
– A new gateway configuration setting, Log client connections and
disconnections, controls whether CICS Transaction Gateway writes a
message each time that a client application program connects to, or
disconnects from, the Gateway daemon. See “Log client connections and
disconnections” on page 56.
v Some beans that were previously provided as part of the CICS Transaction
Gateway product are now, instead, included with the set of sample
programs. See “EPI beans provided in earlier versions of the CICS
Transaction Gateway” on page 224 for details.
v Java Secure Socket Extension (JSSE) is supported.
This gives 128 bit encryption capability and is IBM’s recommended solution
for SSL. For compatibility with previous versions of CICS Transaction
Gateway, this version supports both JSSE and SSLight. However, support
for SSLight might be removed in a future release.
This edition replaces SC34-5933, SC34-5934, SC34-5936, SC34-5937, SC34-5941,
SC34-5942, SC34-5943, and SC34-5944.
Vertical lines at the left side of the page indicate material that is new to this
edition.
© Copyright IBM Corp. 1996, 2002 xiii

xiv CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
Chapter 1. Overview
IBM CICS Transaction Gateway provides secure, easy access from Web
browsers and network computers to CICS applications, using standard
Internet protocols in a range of configurations. It is a robust and scalable
complement to a Web 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. 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
the Windows and UNIX ® operating systems, CICS Transaction Gateway can
access many different types of CICS server. On z/OS CICS Transaction
Gateway can access only CICS Transaction Server for z/OS. See “Supported
software” on page 23 for information on supported operating systems and
CICS servers.
On the Windows and UNIX operating systems, 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 3). On z/OS, CICS
Transaction Gateway can route only ECI requests, and has no Client daemon.
© Copyright IBM Corp. 1996, 2002 1

Overview
Network
computer
Java-enabled
browser
Figure 2 shows how a web client can access CICS programs and data. Note
that the CICS Transaction Gateway is shown as installed on a Web server
machine. This is necessary only if you are using the CICS Transaction
Gateway with Java applets or servlets.
HTTP
HTTPS
SSL
TCP
HTTP
Figure 2. CICS Transaction Gateway
Server machine
Web server
CICS
Transaction
Gateway
Java application
CICS
server
Communication between CICS Transaction Gateway and the client application
uses the following protocols:
v Transmission control protocol/Internet protocol (TCP/IP) sockets
v Hypertext Transfer Protocol (HTTP)
v Secure Sockets Layer (SSL)
v HTTP over SSL (HTTPS)
TCP/IP sockets and SSL provide an efficient method of communication for
intranet applications. Where firewalls exist, HTTP, and its secure alternative
HTTPS, are effective communication protocols for internet applications. See
“Network security” on page 6.
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.
2 CICS Transaction Gateway: UNIX Administration
Local
EPI
ESI
ECI

What CICS Transaction Gateway provides
What CICS Transaction Gateway provides
A Gateway daemon
For security reasons, this is usually resident on a Web server workstation. It
communicates with CICS applications running on CICS servers through ECI,
EPI, or ESI.
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 applications, or Java servlets, and
the Gateway daemon.
v allow client applications to communicate with transactions on a server and
to handle 3270 data streams
v allow your applications to use the SSL network security protocol
J2EE resource adapters
Use these to provide a J2EE-compliant interface to CICS for your 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 between the Gateway and CICS
servers” on page 27. 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 23.
The way the client 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 47.
The external access interfaces (ECI, EPI, ESI)
The external access interfaces allow non-CICS applications to access and
update CICS resources by initiating CICS transactions, or by calling CICS
programs. When used in conjunction with the CICS communication facilities,
they enable 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.
These APIs are provided for both Java and non-Java programming languages.
Chapter 1. Overview 3

What CICS Transaction Gateway provides
External Call Interface (ECI)
The ECI enables a non-CICS client 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 non-CICS client 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)
ESI enables non-CICS client applications to invoke services provided by APPC
password expiry management (PEM). This allows non-CICS applications to verify
that a password matches that recorded by an external security manager (ESM)
for a specified user ID. ESI also allows you to change passwords.
For more information on the external access interfaces, see CICS Transaction
Gateway: Programming Guide and CICS Transaction Gateway: Programming
Reference.
A Terminal Servlet
This allows you to use a Web browser as an emulator for a 3270 CICS
application running on any CICS server. The Terminal Servlet can be used
with a Web server, or servlet engine. The Terminal Servlet provides an
alternative to using EPI. For information on supported Web servers, refer to
“Supported software” on page 23.
Additional functions
3270 terminal emulation (cicsterm)
CICS 3270 terminal emulation enables a 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 (with some exceptions, see Table 5 on
page 28) are autoinstalled at most CICS server systems, and do not have to be
predefined at the server.
4 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Additional functions
3270 printer support (cicsprnt)
CICS 3270 printer support allows you to define a printer terminal on a
Gateway system. This enables CICS applications running on a server to send
output to a printer attached to 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 5 on page 28 for information on which CICS servers currently support
CICS 3270 emulation and hence CICS 3270 client printer support.
CICS Transaction Gateway: local control
Commands are provided to:
v Control the Gateway daemon
You can:
– Specify the TCP/IP port on which the CICS Transaction Gateway listens.
– Specify an initial number of ConnectionManager threads
– Specify a maximum number of ConnectionManager threads
– Specify an initial number of Worker threads
– Specify a 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 hostnames 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
– 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
Chapter 1. Overview 5

|
|
|
|
|
Additional functions
– 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.
CICS Transaction Gateway: remote control
You can:
v Set the trace for the Gateway daemon
v Set JNI trace
v Query trace options
Network security
CICS Transaction Gateway provides comprehensive support for secure
communication, which is critical to successful Internet operation. The secure
network protocols SSL and HTTPS allow your 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 93; the following sections summarize
the functions provided by SSL and HTTPS.
The characteristics of secure communication are:
Confidentiality
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.
Integrity
Messages are not altered during transmission.
Integrity guarantees that the message you sent reaches the recipient
intact. Encryption and digital signatures ensure integrity.
Accountability
The sender and the receiver both agree that the exchange took place.
6 CICS Transaction Gateway: UNIX Administration

Network security
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.
Authenticity
You know who you are talking to and 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:
1. 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.
2. 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
Chapter 1. Overview 7

Network security
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 10.
Digital signatures and digital certificates
A digital signature is a unique, mathematically computed, signature that
ensures accountability.
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 certification 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
8 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
Network security
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 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 certification authority
If you plan to conduct commercial business on the Internet, buy a server
certificate from a CA such as VeriSign or Thawte.
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 may choose to
allow access to only a carefully controlled group of key people within your
intranet.
Your key people should have browsers, such as Netscape Navigator, 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 93 for more information on
obtaining digital certificates.
KeyRings and KeyStores
Digital certificates, public keys, private keys, and trusted root keys are kept in
special types of file which the security protocols can use:
v SSLight, System SSL, and HTTPS use Java class files called KeyRings
v Java Secure Socket Extension (JSSE) uses files called KeyStores
CICS Transaction Gateway uses KeyRings and KeyStores to hold information
about certificates and keys on both the SSL server and SSL clients. See
“SSLight” on page 94, and “Java Secure Socket Extension (JSSE)” on page 104,
for information on how to create these files. The SSL and HTTPS protocols
Chapter 1. Overview 9

Network security
require access to these files to establish secure connections. See “Configuring
CICS Transaction Gateway for SSL and HTTPS” on page 114 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 11 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
10 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
Client Server
Client issues secure session request
(https.//someserver.org/somedata.html)
Server sends X.509 certificate containing server’s public key
Client authenticates certificate against list of known CA’s
(If CA is unknown browser can give user option to accept certificate at user’s risk)
Client generates random symmetric key and encrypts it using server’s public key
Client and server now both know the symmetric key
and encrypt end-user data using symmetric key for duration of session
Figure 3. SSL handshaking with server authentication
Network security
CICS Transaction Gateway supports the following implementations of SSL:
SSLight
An implementation of SSL that is written in pure Java.
This protocol is supported for compatibility with previous
versions of CICS Transaction Gateway. However, support for
SSLight might be removed in a future release.
JSSE
Another Java implementation, that provides support for 128
bit encryption.
IBM recommends that you use JSSE in preference to SSLight.
See “Migration from SSLight” on page 104, for more
information.
System SSL
Chapter 1. Overview 11

Network security
This implementation, which is written in native code, is
supported only for SSL servers on z/OS. It supports hardware
encryption technology available to the z/OS operating system.
HTTPS
HTTPS is a protocol that combines SSL and HTTP, and is used for handling
secure transactions. You specify https:// as an anchor in HTML documents
that link to documents protected by SSL. A client user can also open a URL by
specifying https:// to request an SSL-protected document.
Because HTTPS and HTTP are different protocols, and usually use different
ports (443 and 8080 respectively), you can run both SSL and non-SSL requests
at the same time. This allows you to provide information to all users using no
security, and specific information only to browsers which make secure
requests. This is how retail companies on the Internet allow users to look
through the merchandise without security, but then fill out order forms and
send their credit card numbers using security.
Security exits
CICS Transaction Gateway provides exits that enable the user to define
security operations such as public key encryption. They may also be used for
data compression. Some example source files are provided in this directory:
/samples/java/com/ibm/ctg/samples/security
Java technology
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 book.
This section discusses the Java language, including the types of program that
can be developed, and the security implications.
The Java language
Java is an interpreted object-oriented language, similar to C++. It can be used
to build programs that are independent of operating systems in both source
and object form. Its unique operational characteristics, which span Web
browsers as well as Web servers, enable new and powerful functions in
Internet applications.
To achieve operating system independence, the Java language allows no
operations that are dependent on specific operating system. Also, it excludes
some C++ functions such as a preprocessor, operator overloading, multiple
inheritances, and pointers. All Java programming is encapsulated within
classes, and the Java Development Kit (JDK) includes special classes that are
12 CICS Transaction Gateway: UNIX Administration

|
|
|
|
critical to assuring operating system independence, including GUI functions,
input/output functions, and network communications.
The Java compiler produces an intermediate bytecode format that is machine
independent. This, in turn, is processed at run time by a Java interpreter. The
interpreter also inspects the bytecode at run time to ensure its validity and
safety to the machine environment. Because of the isolation the Java
interpreter provides, it is sometimes referred to as a Java Virtual Machine
(JVM).
The Java language can be used to construct Java servlets, Java applets, and Java
applications.
Java applets
Java applets are supported for compatibility with previous versions of 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 servlets
Java servlets are small Java applications that run on a Web server machine,
unlike Java applets, which are downloaded to a Web browser.
Java servlets have become popular as a replacement for CGI (Common
Gateway Interface) programs. The advantage of Java servlets over CGI
applications is that they can execute more quickly since they are invoked as
threads in a daemon process, meaning that they are persistent in memory and
can fulfill multiple requests.
Note that servlets must ensure references to the gateway objects are
thread-safe.
Java technology
Java applications
A Java application is a program that executes locally on a computer. It has
operating system dependent capabilities in addition to those of an applet. It
can access local files, create and accept general network connections, and call
native C or C++ functions in machine-specific libraries.
Java applications can use the CICS-provided Java classes to perform
transaction processing in CICS systems. They can use the JavaGateway class
to establish two kinds of connection:
v A network gateway connection is a connection across a network to a CICS
Transaction Gateway.
v A local gateway enables a Java application to communicate directly with a
CICS Transaction Server, without the need for a network.
Chapter 1. Overview 13

Java technology
JavaBeans
When the connection between the application and the CICS Transaction
Gateway has been established, an application can use the ECIRequest class,
for example, to do transaction processing.
The JavaBeans API, developed by Sun Microsystems, allows you to write
component software in Java. Components are self-contained, reusable software
units that you can build into servlets using visual application builder tools.
Any JDK Version 1.1-compliant browser or tool supports JavaBeans.
JavaBeans components are called beans. Most builder tools allow you to
maintain beans in a palette or toolbox. You can select a particular bean from
the toolbox, drop it onto a form, modify its appearance and behavior, and
define how it interacts with other beans. You can build your selected bean
and other beans into a servlet, or new bean, without actually writing any
code. For more information on JavaBeans, see the Sun Web site
(www.java.sun.com).
The CICS Transaction Gateway provides EPI Java bean samples based on
high-level EPI interfaces. These beans allow you easily to create Java
programs that access data from existing CICS 3270 applications, without any
programming. Using a bean composer tool, you can quickly and easily create
new Java front-ends that can connect to CICS, run transactions, display data
from 3270 screens, and send user input back to the CICS server. For more
information, see the CICS Transaction Gateway: Programming Guide.
Firewalls
A current design consideration in the use of Java applet communication is the
impact of firewalls. This is the term given to a configuration of software that
prevents unauthorized traffic between a trusted network and an untrusted
network. Firewalls are put in place to protect company assets from outside
intrusion, but they can also limit legitimate communications. Firewalls have
two functions:
1. To restrict access to a server by outside users - inbound restrictions
2. To limit the ability of users inside a firewall to perform certain network
functions outside their firewall - outbound restrictions.
A CICS Transaction Gateway configuration is well suited to avoid problems in
the first area since the Gateway processor can be placed outside the firewall
and be connected through the firewall to the CICS server. Outbound firewalls
that users may have to contend with can be a problem. A large company
might use a firewall to limit the types of connections and protocols that can
be used.
The use of Java on an intranet (a local implementation of the Internet) works
very well since firewalls are typically not a factor. If you are designing
14 CICS Transaction Gateway: UNIX Administration

Java technology
applications to run over the Internet (rather than an intranet), determine
whether your potential users are behind firewalls. If so, consider alternative
processing for those users, such as executing the Java code as a Java servlet
on the Web server. Also consider using HTTP and HTTPS protocols supported
by CICS Transaction Gateway, see “Authentication using SSL” on page 10 and
“HTTPS” on page 12.
Web servers
A Web server is a software program that responds to information requests
generated by Web browsers. When a request from a browser is received, the
Web server processes the request to determine the action to take:
v Return the requested document.
v Deny the request.
v Pass the request through for further processing by an external application.
The request might be, for example, to a database to perform a search
request, or to a more dynamic form of information delivery such as Lotus ®
Domino .
Communication between a Web server and an external application is
transparent; you need to know only the URL of the Web server to direct a
request to it. Also, all Web servers can handle requests from many browsers
concurrently.
Specialized servers can also be configured to limit access to a restricted set of
users, or to provide security for purchase of goods or services.
Web servers exist for almost every operating system and are available from
many suppliers. For information on the Web servers supported by CICS
Transaction Gateway, see “Supported software” on page 23.
The J2EE resource adapters
An API in the CICS Transaction Gateway allows Java programmers to take
advantage of features provided in J2EE-compliant runtime environments (e.g.
IBM WebSphere Application Server). The J2EE resource adapter defines a
standard architecture for connecting the Java 2 Platform, Enterprise Edition
(J2EE) to heterogeneous Enterprise Information Systems (EIS) such as CICS.
The resource adapter architecture defines a set of scalable, secure, and
transactional mechanisms that enable the integration of EISs with application
servers and enterprise applications.
A proprietary application server, such as IBM WebSphere, can be extended to
support the resource adapter architecture, and is then assured of a seamless
Chapter 1. Overview 15

Introduction
connectivity to multiple EISs. Similarly, a vendor provides a standard resource
adapter that can connect any application server that supports the resource
adapter architecture to an EIS.
The resource adapter architecture defines a Common Client Interface (CCI) for
EIS access. The CCI defines a client API for interacting with heterogeneous
EISs. The resource adapter architecture enables a vendor such as IBM to
provide a standard resource adapter to allow access to its product. This
resource adapter connects 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 which are provided.
The samples.txt file, in the \samples subdirectory, provides
additional information on the J2EE sample programs.
How CICS Transaction Gateway accesses CICS
This section describes how CICS Transaction Gateway allows Java servlets to
access CICS programs and data.
1. The Web server loads and initializes the servlet. This could be when the
Web server starts, or when the first request is made to the servlet by the
Web browser or network computer.
2. The servlet creates a JavaGateway object to connect to the CICS
Transaction Gateway. This establishes communication between the
browser and the long running Gateway daemon process using Java’s
sockets protocol.
3. When a HTTP request from the Web browser or network computer
invokes the servlet, the Web server calls its Service method with details
of the request.
4. The servlet creates an ECIRequest, EPIRequest, orESIRequest object,
that contains ECI, EPI, or ESI calls, and sends it to the Gateway daemon
using the JavaGateway.flow method.
5. The Gateway daemon receives, and unpacks the request. The Client
daemon makes corresponding ECI, EPI, or ESI calls to the CICS server.
6. The CICS server processes the calls, including verification of the userid
and password if required, and passes control and user data to the CICS
application program.
7. When the CICS application program has finished processing, it returns
control and data to CICS.
8. The CICS server returns control and data to the Client daemon.
16 CICS Transaction Gateway: UNIX Administration

9. The Gateway daemon packs these results and returns them to the Java
servlet.
10. When the servlet receives the results, it generates a HTTP response to
return to the Web browser.
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 clients. The threading model uses the following objects:
ConnectionManagers
A ConnectionManager manages all the connections from a particular Java
client. When it receives a request, it allocates a Worker thread from a pool of
available Worker threads to execute the request.
Workers
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.
You can set both the initial and maximum sizes of the resource pools for these
objects; see “Configuring CICS Transaction Gateway 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 with user-specified options” on page 132.
Table 3 shows thread limits that should be considered when setting the
number of Connection Manager and Worker threads on the various operating
systems:
Table 3. Thread limits on CICS Transaction Gateway operating systems
Operating
system
System-wide limit of
the maximum number
of threads
z/OS This may be restricted
by the total number of
MVS ® Task Control
Blocks (one is created
per UNIX System
Services thread)
How CICS Transaction Gateway accesses CICS
Process limit of the number of threads
Governed by the UNIX System Services
parameters: MAXTHREADS and
MAXTHREADTASKS
Windows No limit Limited by the amount of virtual memory
available for the process (by default a
thread has 1M of stack meaning that 2028
threads can be created per process)
Chapter 1. Overview 17

The CICS Transaction Gateway: threading model
Table 3. Thread limits on CICS Transaction Gateway operating systems (continued)
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 Configurable Kernel
Parameters in the SAM utility)
1024 (refer to your LinuxThreads
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
book.
The threading model is illustrated in the following figures:
Figure 4. CICS Transaction Gateway threading model for TCP/IP and SSL. These protocols have a persistent socket.
18 CICS Transaction Gateway: UNIX Administration

CICS Transaction Gateway and object request brokers
Figure 5. CICS Transaction Gateway threading model for HTTP/HTTPS. These protocols do not have a persistent
socket.
CICS Transaction Gateway and object request brokers
Some Web servers contain an object request broker (ORB) that conforms to the
Object Management Group’s (OMG) Common Object Request Broker
(CORBA) standard. If you have such a Web server, you can develop servlet
objects that can be invoked from a remote browser using the CORBA Internet
InterORB Protocol (IIOP). IIOP is transmitted to the browser using HTTP.
Chapter 1. Overview 19

20 CICS Transaction Gateway: UNIX Administration

Chapter 2. Planning your installation
This chapter helps you to plan the installation of the CICS Transaction
Gateway by listing the hardware and software that you need. For information
about hardware and software requirements on all supported operating
systems, see Appendix B, “Hardware and software” on page 229. The CICS
servers to which CICS Transaction Gateway can connect are also listed.
The Chapter consists of the following topics:
“Hardware requirements” on page 22 Read this for information about the
hardware you need to run your CICS
Transaction Gateway (processor type,
memory, disk space).
“Supported software” on page 23 Read this for information about the
software products that are supported for
use with your CICS Transaction Gateway.
“CICS server PTF requirements” on
page 26
“Communication between the Gateway
and CICS servers” on page 27
Read this for information about APARs
and PTFs (service updates) for CICS
servers.
Read this for information about the
communications protocols you can use to
connect to your CICS servers.
“DBCS Multibyte Characters” on page 29 Read this for information about support
for multibyte characters.
If you are using an earlier version of the product, or a CICS Universal Client,
see Chapter 14, “Migration” on page 217 for a discussion of migration issues.
See the product readme file for any late changes to hardware and software
requirements.
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 README.LNX
Solaris README.SOL
© Copyright IBM Corp. 1996, 2002 21

Planning
Hardware requirements
If you have 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.
Table 4. Hardware requirements on UNIX systems
AIX LINUX SOLARIS HP-UX
Processor v IBM RISC
System/6000 ®®
v IBM RS/6000 ®®
Scalable
POWERParallel
System (SP2 ® G5, G6, MP3000 or
above
SPARC PA-RISC 1.1 or 2.0
).
Terminals Any type of
terminal or
X/Terminal that
can attach to the
processor.
Any standard
telnet or X based
terminal that can
access Linux.
Any type of
terminal or
X/Terminal that
can attach to the
processor.
Any standard
telnet or X based
terminal that can
access HP-UX.
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB
Disk space 30MB,plus30MB
for temporary files
used during
installation.
22 CICS Transaction Gateway: UNIX Administration
30MB,plus30MB
for temporary files
used during
installation.
30MB,plus30MB
for temporary files
used during
installation.
30MB,plus30MB
for temporary files
used during
installation.

Supported software
The following products are supported.
Operating systems
CICS Transaction Gateway is supported on the following operating systems:
v AIX V4.3.3 with Service Pack 25
v AIX 5.1
v HP-UX 11.0
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)
v Linux for S/390 ® - SuSE 7.0 (Kernel level 2.2.16)
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)
v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)
Web browsers
Supported software
v HTML/HTTP functions: Any browser that supports HTML V1.0 should
work with the product.
v Java Functions: Any JDK 1.1 compliant Web browser should work with the
product.
The CICS Transaction Gateway is supported with the following browsers:
v Microsoft ® Internet Explorer 5.0, 5.5 and 6.0
v Netscape Communicator 4.7 and 6.2
v HotJava Browser V 1.1 (for Solaris)
Note: Applets running within the JVM supplied with the Netscape
Communicator browser fail to make successful connections with the
CICS Transaction Gateway. Message number CCL6652E is returned to
the applet. Currently there is no solution to this problem.
Java applets are supported for compatibility with previous versions of
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.
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 going in
as. Currently there is no solution to this problem.
Chapter 2. Planning your installation 23

Supported software
JDK levels
CICS Transaction Gateway supports JDK levels 1.3 and 1.3.1 at the following
minimum service levels:
v AIX: IBM Java SDK 1.3 (service release 6)
v HP-UX: Java SDK 1.3.0.02
v Solaris: Sun Java SDK SE 1.3.0_04.
JSSE
CICS Transaction Gateway supports JSSE in the the following environments:
v Standard Java runtime environment (JRE).
Only the IBM JSSE is supported:
– AIX: Install the JSSE package supplied with CICS Transaction Gateway
– HP-UX: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
– Linux for S/390: Install the JSSE package supplied with CICS Transaction
Gateway
– Solaris: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
v WebSphere Application Server:
All supported levels have built in JSSE support.
CICS Transaction Gateway does not support the use of JSSE with applets.
CICS Servers
A CICS server runs real-time multi-user applications and manages the
associated resources and data. CICS Transaction Gateway is supported with
the following servers:
v CICS Transaction Server for z/OS V2.2
v CICS Transaction Server for z/OS V2.1 (with APAR PQ30168, for signon
capable terminals, applied)
v CICS Transaction Server for z/OS V1.3 with APAR PQ30168, for signon
capable terminals, applied.
v CICS for MVS/ESA V4.1, with communication through SNA. (with APAR
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for
EPI emulation. APAR PN79262 is needed for DBCS support.
v CICS for OS/400 ® V4.4
v CICS Transaction Server for OS/2 ® V4.1 with CSD 3
v CICS Transaction Server for VSE/ESA 1.1.0 (with APAR PQ30170, for
signon capable terminals, applied), or a minimum service level of 1.1.1
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)
24 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
v TXSeries V5.0 (Windows, AIX)
Supported software
Web servers
Any web server that is supported by your application server should work
with the product.
Application servers
The CICS Transaction Gateway is supported with the following:
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,
AIX and Solaris.
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.
SNA communications
Customers wishing to use SNA communications should install one of the
following products:
AIX
IBM eNetwork Communications Server V6.1, with a minimum of service
level 1 (AIX).
SNA is not supported on other UNIX operating systems.
TCP/IP communications
TCP/IP support is provided by the operating system.
TCP62 communications
TCP62 support is provided by CICS Transaction Gateway.
Compilers and application development tools
CICS Transaction Gateway is supported with the following compilers and
application development tools:
AIX
v IBM C for AIX V4.4
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6
v IBM VisualAge ® C++ Professional V4.0
v IBM VisualAge C++ Professional V5.0 (requires AIX version 4.2 or later)
HP-UX
v HP ANSI C B.11.01, with a minimum of service level 7
v HP aC++ B.11.01, with a minimum of service level 6
Linux for S/390
v GNU compiler C runtime V2.95, with a minimum of service level 2
v GNU compiler C++ runtime V2.95, with a minimum of service level 2
Solaris
Sun WorkShop C++ V5.0
Chapter 2. Planning your installation 25

|
|
|
Supported software
Note: The C++ compiler must have all available service patches applied.
Other tools
These tools are available for viewing the PDF online documents:
v Adobe Acrobat Reader V5.0
v GhostView V4.0 on Linux
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 Signon capability
CICS Servers require APAR fixes to support the terminal signon capability
function available in this release; see “Supported software” on page 23 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 on CICSTERM,
the installed terminal will give unpredictable results.
Timeout support
To provide complete support for timeouts, if you are using any TXSeries or
Transaction Server on UNIX and Windows operating systems, it must include
the appropriate PTF level; see “Supported software” on page 23 for details.
If the server does not have the required APAR applied and the ’-a’ option is
not specified on CICSTERM, this happens:
v The CICS Transaction Gateway displays the message: CCL7053E Errors
found while communicating with server
v CCL3105 Inbound CICS datastream error (CTIN, 4, 0) is written to
CICSCLI.LOG
26 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
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 between the Gateway and CICS servers
Supported software
You can use these protocols to communicate with CICS servers:
TCP/IP Transmission Control Protocol/Internet Protocol (TCP/IP) is a
widely used, robust, suite of protocols, particularly important
in connecting heterogeneous networks.
SNA (AIX operating system only)
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 Systems Network
Architecture (SNA) flows over an IP network.
The protocols that you can use for the various client/server connections are
shown in Table 5 on page 28. This table lists the protocols that you can use to
connect your CICS Transaction Gateway to your CICS server. It also shows
whether ECI, EPI emulation, and Autoinstall are supported for your
combination of CICS server and CICS Transaction Gateway operating system.
Chapter 2. Planning your installation 27

Communication protocols
Table 5. 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. Otherwise, *
means supported on Windows and all UNIX operating systems; V means not supported.
SERVER TCP/IP SNA TCP62 ECI
CICS for MVS/ESA
V4.1
CICS for OS/400
V4.4
CICS Transaction
Server for OS/2 V4.1
CICS Transaction
Server for z/OS V1.2
and V1.3
CICS Transaction
Server for VSE/ESA
V1.1.0 and V1.1.1
V
*
*
V
V
CICS/VSE V2.3 V
TXSeries V4.2
(HP-UX)
TXSeries V4.3 (AIX,
Solaris, Windows )
*
*
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
AIX
Windows
* *
EPI
Emulation
See note
AIX
HP-UX
Solaris
Windows
ESI
*
* * * *
V * * V
* *
V *
V *
Windows
AIX
HP-UX
Solaris
Windows
AIX
HP-UX
Solaris
AIX
HP-UX
Solaris
Windows
V * * V
V * * V
Note: EPI always incorporates CICS 3270 terminal emulation and CICS 3270
client printer support.
All servers support autoinstall. This means that you do not need to predefine
the client to the CICS server; control table definitions are automatically
created for the client at the CICS server. For CICS/VSE, autoinstall is possible
via LU 6.2 single session only. This restriction does not affect CICS Transaction
Server for VSE/ESA.
Restrictions on CICS for OS/400
The following restrictions apply:
v DBCS languages are not supported.
28 CICS Transaction Gateway: UNIX Administration
*
V
V

|
|
|
|
|
|
|
Communication protocols
v Signon 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 5 some protocols can be used only for certain types of
client/server connection.
If you need to connect different types of networks, for example, Token Ring
and Ethernet networks, consider using TCP/IP.
TCP62 allows access to CICS Transaction Server for z/OS over a TCP/IP
network. Partner LU62 applications can communicate without complex SNA
configuration definitions on the client, and without any changes to the LU62
applications on the client or server. If you require easy client access to CICS
Transaction Server for z/OS over your TCP/IP network, use the TCP62
support. For information on configuring TCP62, see “TCP62 configuration” on
page 38.
DBCS Multibyte Characters
Some characters in certain codesets are represented with 3 or more bytes. The
CICS Transaction Gateway for the UNIX operating systems 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 an AIX or Solaris-unique locale, you might experience
problems when connecting to certain CICS servers. The table below lists the
relevant client/server combinations.
CICS Client Codepage CICS Server operating
system
CICS Server Codepage
ja_JP (33722) OS/2 932
ja_JP (33722) Windows NT 932
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
Chapter 2. Planning your installation 29

Communication protocols
30 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Chapter 3. Installation
This chapter describes how to install the CICS Transaction Gateway. It consists
of the following:
“Installing the CICS Transaction
Gateway”
Read this for detailed instructions on how
to install your CICS Transaction Gateway.
“National language support” on page 33 Read this for information on:
v Changing the language in which the
Gateway displays user messages
v Using alternative code sets
“Using X-Windows from a remote Read this for information on how to
system” on page 35
access z/OS applications from a remote
system.
“Uninstalling the CICS Transaction Read this if you wish to uninstall the
Gateway” on page 35
CICS Transaction Gateway.
Installing the CICS Transaction Gateway
To install the CICS Transaction Gateway:
1. Log in as root.
2. Stop any Client daemon that is running (issue the cicscli -i command).
AIX
3. Run the slibclean command to remove any unused libraries.
End of AIX
4. The CICS Transaction Gateway is distributed as a compressed tar or rpm
file containing an executable script file. When run, the script file creates
the library files, commands, messages and customization (.INI) files. Find
the file on the distribution medium. Figure 6 on page 32 lists the filenames.
© Copyright IBM Corp. 1996, 2002 31

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation
Operating system File name
AIX ctg-500x.tar.Z
HP-UX ctg-500h.tar.Z
Linux ctg-5.0.0-1.s390.rpm
Solaris ctg-500s.tar.Z
Figure 6. Installation files
5. Copy the tar file to a working directory on your hard disk.
6. Proceed as follows:
AIX, HP-UX and Solaris
Uncompress the file and extract the files:
uncompress
tar -xf
where is the filename in Figure 6 for your
operating system, and is the same name without
the .Z.
This creates a script file called ctginstall in the current directory.
Linux
Issue the following command:
rpm -Uvh ctg-5.0.0-1.s390.rpm
This creates a command ctginstall.
7. Install the CICS Transaction Gateway by entering:
ctginstall
8. Read and accept the license agreement to continue the installation. If the
agreement does not display properly, restart the installation using the
command ctginstall 40. This sets your screen width to 40 characters
during installation.
To view the license agreement after installation, issue the command
ctgbrowse. If the agreement does not display properly, issue the command
ctgbrowse 40.
9. On all operating systems except AIX, refer to “Configuring message
queues” on page 44 for advice on configuring your system to allow large
client data flows.
32 CICS Transaction Gateway: UNIX Administration

National language support
You can select the language in which user messages are displayed by the
CICS Transaction Gateway by entering the command:
ctgmsgs XX
where XX is the two character message language. To obtain a list of available
languages, enter the command without parameters. Figure 7 shows the
output:
CICS Client for AIX - User messages
-----------------------------------
Language Locale Code Set
--------------------- --------- -----------us
US English en_US ISO8859-1
EN_US UTF-8
fr French fr_FR ISO8859-
FR_FR UTF-8
de German de_DE ISO8859-1
DE_DE UTF-8
it Italian it_IT ISO8859-1
IT_IT UTF-8
es Spanish es_ES ISO8859-1
ES_ES UTF-8
tr Turkish tr_TR ISO8859-9
TR_TR UTF-8
jp Japanese Ja_JP IBM-943
ja_JP IBM-eucJP
JA_JP UTF-8
kr Korean ko_KR IBM-eucKR
KO_KR UTF-8
cn Simplified Chinese zh_CN IBM-1386
zh_CN IBM-eucCN
ZH_CN UTF-8
Syntax: ctgmsgs
Figure 7. Output from the ctgmsgs command (AIX system)
National language support
This also shows the locale and code set associated with the language.
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. Installation 33

National language support
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 /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 (other UNIX platforms)
To use an alternate code set, use the iconv routine for the flat file
/CCLMSG.TXT. For example, to convert
/CCLMSG.TXT from code set ISO8859-1 to code set ISO-850
enter:
iconv -f ISO8859-1 -t ISO-850 /CCLMSG.TXT > CCLMSG.NEW
When you have done this conversion, you can overwrite the CCLMSG.TXT
file with the new file:
34 CICS Transaction Gateway: UNIX Administration

mv CCLMSG.NEW /CCLMSG.TXT
Using X-Windows from a remote system
When using X-Windows from a remote system, for example, to access the
configuration tool and iKeyman, you must set up the DISPLAY environment
variable to allow the application to display its windows on that system.
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:
DISPLAY=disp:0.0
followed by
export DISPLAY
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.
Uninstalling the CICS Transaction Gateway
To uninstall the CICS Transaction Gateway issue the command:
ctguninst
National language support
On Linux, the command rpm -e ctg-5.0.0-1 also uninstalls the CICS
Transaction Gateway.
Chapter 3. Installation 35

36 CICS Transaction Gateway: UNIX Administration

Chapter 4. Setting up communication with CICS servers
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. This
chapter consists of the following:
“TCP/IP configuration” Read this if you will use TCP/IP.
“TCP62 configuration” on page 38 Read this if you will use TCP62.
“Data conversion” on page 44 Read this for information on how data
may be converted as it passes between
the CICS Transaction Gateway and a
CICS server.
“Configuring message queues” on page 44 Read this if you are running HP-UX,
LINUX or Solaris, for information on
configuring your system for large data
flows.
A number of sample configuration documents provide step-by-step guidance
on configuring the CICS Transaction Gateway and CICS servers for different
scenarios. If one of the documents covers your desired configuration, simply
follow the instructions in it. See “Sample configuration documents” on
page 238.
After you have set up your communications links, continue at Chapter 5,
“Configuration” on page 47. This tells you how to make the required entries
in the configuration file.
TCP/IP configuration
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
© Copyright IBM Corp. 1996, 2002 37

|
|
|
|
|
|
|
|
TCP/IP configuration
where 192.113.36.200 is the IP the address of your CICS server. If you are
using a Domain Name Server (DNS), you can specify the symbolic hostname
rather than the IP address of the server.
To stop the PING command, press the Ctrl+C keys simultaneously.
If TCP/IP is configured correctly, you see messages as shown in the following
figure:
ping 192.113.36.200 56 3
PING 192.113.36.200: 56 data bytes
64 bytes from 192.113.36.200: icmp_seq=0 ttl=255 time=3 ms
64 bytes from 192.113.36.200: icmp_seq=1 ttl=255 time=3 ms
64 bytes from 192.113.36.200: icmp_seq=2 ttl=255 time=3 ms
----192.113.36.200 PING Statistics----
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 3/3/3 ms
#
Figure 8. Example messages returned by ping command
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. This example is from an AIX machine.
Refer to “TCP/IP settings” on page 72 for information on TCP/IP settings.
Next steps
1. Use the configuration tool to create a server definition; see “The
configuration tool interface” on page 51.
2. Configure the server definition (see “TCP/IP settings” on page 72):
Specify TCP/IP as the protocol.
Enter the hostname or IP address of your CICS server.
TCP62 configuration
The TCP62 support for CICS Transaction Gateway allows communication with
CICS for MVS/ESA Version 4.1 and later over a TCP/IP network.
On CICS for MVS/ESA Version 4.1 and CICS Transaction Server for z/OS,
you can use autoinstall to define SNA client connections. The advantage of
38 CICS Transaction Gateway: UNIX Administration

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 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.
Enabling 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. For more details, see “Sample
configuration documents” on page 238, and “Redbooks” on page 239. You also
need to make entries in the configuration file; see Chapter 5, “Configuration”
on page 47.
Table 6 shows the entries that you need to make. The values in the Example
column are taken from the sample configuration documents.
Table 6. 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
hursley.ibm.com
NETID - Partner LU name. The
Partner LU name is
NETID.APPL.
ABC3XYZ4
APPL Applid Partner LU name IYCKCTU1
LOGMODE Modename Mode name LU62PS
IP address mask for
LU name template
(optional)
TCP/IP subnet mask FFFFFE00
Fully qualified CP
name or template
Local LU name or
template
TCP62 configuration
ABC3XYZ4.PQRS1234
CCLI****
Chapter 4. Setting up communication with CICS servers 39

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
TCP62 configuration
On z/OS
1. Define the TCP/IP address and hostname 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 book, SC31-6527.
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 have 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. 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:
1. Set the following SIT parameters:
ISC=YES
APPLID=IYCKCTU1
AIEXIT=DFHZATDY
where IYCKCTU1 is the VTAM APPL that you defined earlier.
2. Install these groups:
v DFHISC
v DFHCLNT
3. Define an SNA connection to the client workstation. (You can define the
connection statically, or autoinstall it.)
40 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
v On the MODENAME option of the SESSIONS definition, specify the
same modename as your VTAM LOGMODE. You will also use this
value in 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 76. The default is 8;
increase this if necessary. Specify the second value as 1, that is, that
CICS is to have one contention winner. For example, MAXIMUM(8,1)
means that the modeset is to support eight sessions, and that CICS has
one contention winner.
On the 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 Place 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 76.
KeepAlive packets
When using CICS Transaction Gateway, with the TCP62 protocol, KeepAlive
packets can be sent to the CICS server to check its availability.
KeepAlive packets are enabled by default.
TCP62 configuration
You can enable or disable the sending of KeepAlive packets using the Remote
node inactivity poll interval setting in the configuration tool; see “Remote node
inactivity poll interval” on page 76.
Changing this inactivity poll value alters how frequently CICS Transaction
Gateway sends KeepAlive packets. A higher interval value will result in less
network traffic but CICS Transaction Gateway will take longer to detect that a
Chapter 4. Setting up communication with CICS servers 41

|
|
|
|
TCP62 configuration
connection has been lost. With a lower value the opposite is true, lost
connections are detected and there ish a greater amount of network traffic.
Next steps
1. Use the configuration tool to create a server definition using the TCP62
protocol; see “The configuration tool interface” on page 51.
2. Configure the server definition (see “TCP62 settings” on page 73).
SNA configuration (AIX only)
To set up communication over SNA, define the following in your SNA
communications product:
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 (PLU) 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 SNA support. The terms used above are the ones used by
IBM eNetwork Communications Server.
SNA links to the CICS Transaction Gateway support data synchronization
levels (sync levels) 0 and 1.
Configuring SNA for the CICS Transaction Gateway for AIX
To run the SNA transport, install and configure a SNA Server, such as IBM
Communications Server for AIX Version 6.0.1.0. You need to make entries on
VTAM, CICS, Communications Server for AIX, and the CICS Transaction
Gateway. Table 7 shows the entries that you need to make.
Table 7. Matching definitions for SNA
VTAM CICS
Transaction
Server
IBM
Communications
Server for AIX
NETID — First part of fully
qualified LU name
in Partner LU
42 CICS Transaction Gateway: UNIX Administration
CTG.INI Example
— ABC3XYZ4

Table 7. Matching definitions for SNA (continued)
VTAM CICS
Transaction
Server
IBM
Communications
Server for AIX
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
— Adjacent node
MAC address in
Link Station
APPL APPLID Second part of
fully qualified LU
name in Partner
LU
Configuring SNA
CTG.INI Example
— IYAMR021
Local LU name IYAMT210
— 05d316fc
— 400045121088
— IYCQST34
LogMode Modename Name in Mode Mode name LU62PS
— — — Partner LU name IYCQST34
Notes:
1. The NETID is the VTAM SNA 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. The token ring destination address is the MAC address of the
communications adapter used by the VTAM front end processor. This
might by a Communications Controller such as the 3172,or a 2216 router,
or an OSA adapter.
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.
Chapter 4. Setting up communication with CICS servers 43

Configuring SNA
Data conversion
8. The Host system control point name is the CP for the PU of the VTAM
front end processor.
More information on connecting CICS Transaction Gateway to CICS
Transaction Server for z/OS is in CICS Transaction Gateway V3.1 The WebSphere
Connector for CICS. See also “Sample configuration documents” on page 238,
for step-by-step guidance on configuration for specific scenarios.
To enable ATI against client terminals, define the transaction program CRSR
on the SNA Server. Follow the instructions in the SNA Administration Guide.
To define the transaction program using the X-Windows utility:
1. Start the SNA administration application, xsnaadmin.
2. Select Services—>APPC—> Transaction Programs.
3. Select TP invocation and the Add button.
4. Enter CRSR as the Application TP.
5. Indicate Parameters are for invocation on any LU Queue incoming
allocates and enter the path to the executable as: /usr/sbin/cclclnt
6. Set Arguments to CRSR
7. Set Userid to root and Group to system.
8. Close the TP definition window.
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 may have 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/390 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 225.
Configuring message queues
In UNIX 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 Messages like the following are displayed:
44 CICS Transaction Gateway: UNIX Administration

CCL9116 Unable to send message to queue ’NNNN’
CCL9117 This may be because you have not changed your system to allow large
IPC queues
CCL9118 Consult the CICS client troubleshooting documentation for further
information on how to do this
IBM recommends 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 UNIX system:
v “Message queues on HP-UX”
v “Message queues on LINUX” on page 46
v “Message queues on Solaris” on page 46
HP-UX
IBM recommends the following settings:
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
Configuring SNA
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.
Chapter 4. Setting up communication with CICS servers 45

Configuring SNA
Linux
IBM recommends the following settings:
#define MSGMAX 40960 /* max size of message (bytes) */
#define MSGMNB 163840 /* default max size of a message queue */
#define MSGQNUM 20480 /* max messages in flight / queue */
Set these values by changing the entries in the
/usr/src/linux/include/linux/msg.h file. Refer to your Linux kernel source
documentation for information on how to change the file and rebuild your
kernel image.
End of Linux
Solaris
IBM recommends the following settings:
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” on page 209 for information on changing this file.
46 CICS Transaction Gateway: UNIX Administration
End of Solaris

Chapter 5. Configuration
This chapter describes how to configure your CICS Transaction Gateway. It
consists of the following:
“Before you start” on page 48 Read this for information on what to do
before configuring the CICS Transaction
Gateway.
“Using the configuration tool” on page 49 Read this for general information on
configuring the CICS Transaction
Gateway, including:
v How to change the default location of
your configuration details
v Using the Task Guide to define basic
details about your CICS server and the
protocols you will use
“Configuring CICS Transaction Gateway
settings” on page 53
“Configuring Client settings” on page 66
“Configuring Server settings” on page 70
Read this if you want to allow non-CICS
applications written in Java to
communicate with CICS servers.
Read these sections if you want to set up
communication with CICS servers.
“Editing the configuration file” on page 80 Read this if you prefer to edit the
configuration file direct, rather than use
the configuration tool.
“Keyboard mapping for cicsterm” on
page 88
“Customizing the screen colors for
cicsterm” on page 90
“Preparing to use local CICS Transaction
Gateway support” on page 92
Read these sections if you intend to use
cicsterm.
Read this for information on setting up
your Java environment correctly.
A number of sample configuration documents provide step-by-step guidance
on configuring the CICS Transaction Gateway and CICS servers for different
scenarios. If one of the documents covers your desired configuration, simply
follow the instructions in it. See “Sample configuration documents” on
page 238.
See also:
v IBM Redbooks (see “Redbooks” on page 239)
v Chapter 4, “Setting up communication with CICS servers” on page 37
© Copyright IBM Corp. 1996, 2002 47

Configuration
Before you start
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.
Note: You must restart the Client daemon and the Gateway daemon for any
changes to the configuration file to take effect.
Gather information
Have the following information available:
v The protocol you will use to connect to the CICS server (TCP/IP, TCP62,
SNAon AIX only)
v The hostname or IP address of the server
v The port number at the server to which the Client daemon should connect
v The protocols you will use with the Gateway (TCP, SSL, HTTP and HTTPS)
See Table 6 on page 39, and Table 7 on page 42, for information on matching
definitions for TCP62 and SNA.
Configure your programming environment
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)
v cfwk.zip (if you are using SSLight security)
These archives are in the /classes subdirectory.
Set the CLASSPATH
Use a shell command like the following to set the CLASSPATH environment
variable:
export CLASSPATH=.:/usr/local/classes:/classes/ctgclient.jar:${CLASSPATH}
Figure 9. Shell command for AIX:
48 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
export CLASSPATH=.:/opt/classes:/classes/ctgclient.jar:${CLASSPATH}
Figure 10. Shell command for Linux, Solaris or HP-UX :
This shell command makes the classes in the current directory, and in
directory /usr/local/classes on AIX, or directory /opt/classes on Linux,
Solaris, and HP-UX, accessible by the JVM. It also makes the ctgclient.jar
archive accessible by the JVM.
You can place the shell command in the .profile file in your home directory
so that the CLASSPATH environment variable is automatically set when you log
on to your system.
Use the following shell command to display the value of the CLASSPATH
environment variable:
echo $CLASSPATH
Recommended Java options for the Solaris JVM
For Gateway applications running under Java 1.3.0, you are recommended to
use the -XX:+UseLWPSynchronization Java option.
Also ensure that /usr/lib/lwp appears before /usr/lib in the
LD_LIBRARY_PATH variable.
If you do not set these options, calls to the JavaGateway.open() method might
hang when using the TCP/IP protocol. See your Solaris documentation for
more details.
Using the configuration tool
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-Windows from a remote system” on
page 35.
Configuration
To start the configuration tool, enter the ctgcfg command.
Task Guide
The first time you run the configuration tool, you are asked if you want to
use the Task Guide to define basic information about your system. The
Task Guide allows you to enter details of your CICS servers, and enable
the TCP and HTTP protocols for the Java gateway. You can change any of
the settings you enter here later, through the configuration tool. You can
bypass the Task Guide, and go straight to the configuration tool, by
Chapter 5. Configuration 49

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Configuration
clicking No when asked if you want to use the Task Guide. You are
recommended to use the Task Guide unless you use a screenreader; see
“Accessibility” on page 241.
For help in completing any of the screens on the Task Guide, refer to the
online help, or the relevant section in “The configuration tool interface” on
page 51.
The configuration file
Configuration details are stored by default in the CTG.INI file in the
/bin subdirectory. IBM recommends that you use the
configuration tool to update this file.
You can specify a different path to the configuration file by setting the
CICSCLI environment variable. (The CICS Transaction Gateway log
indicates the location of CTG.INI.) The CICS Transaction Gateway will not
run if a configuration file is not found.
The Task Guide also launches if it fails to find CTG.INI in the
/bin subdirectory. If you specified a different location for
the configuration file through the CICSCLI environment variable, and
wish to edit an existing configuration file, click No when asked if you
want to use the Task Guide. Once the configuration tool has launched,
open your configuration file.
Running the configuration tool on a different operating system
You can use the configuration tool on any of the other CICS Transaction
Gateway operating systems to generate a configuration file for your operating
system. See Appendix B, “Hardware and software” on page 229 for other
supported operating systems.
1. Install 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:
Operating system Command
AIX ctgcfg -PLAT AIX
HP-UX ctgcfg -PLAT HPUX
Linux ctgcfg -PLAT L390
Solaris ctgcfg -PLAT SOL
Windows ctgcfg -PLAT WIN
This makes the configuration tool run as if it is on your operating system.
50 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
4. Make the required entries and click Save. This creates or updates the
CTG.INI file.
5. Use FTP in ASCII mode to transfer the file to your system.
The configuration tool interface
The screen has four input areas (described separately below):
1. Menu bar
2. Toolbar
3. Tree structure
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.
Figure 11. The configuration tool
Configuration
Note: Screen captures later in this chapter are taken from the Windows
version of the configuration tool. On your platform, the configuration
tool may look slightly different.
Tree structure
The tree structure (see Figure 11) allows you to navigate through all of the
settings in your configuration. The types of root node are as follows:
Chapter 5. Configuration 51

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Configuration
Java Gateway Contains a subnode for each protocol that the CICS
Transaction Gateway can use (TCP, SSL, HTTP, HTTPS and
TCPAdmin).
Client Contains a subnode for each of your server definitions.
Menu bar
The menu bar contains the File, Edit, Tools, Settings, and Help pulldowns.
The File pulldown has the following options:
New Creates a new configuration.
Open Opens an existing configuration.
Save Saves the current configuration. If a new configuration has
been created, the file name is CTG.INI (in 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 pulldown has Cut, Copy and Paste options, which perform the
standard text functions.
The Tools pulldown has the following options:
Trace Settings Displays the Trace Settings dialog.
Task Guide Starts the Task Guide for creating new server definitions.
New Server Defines a new server named A_Server, that uses the TCP
protocol. Recommended for users of screenreaders and expert
users; otherwise use the Task Guide option.
Delete Server Deletes a server node from the tree structure.
The Settings pulldown 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.
Any changes that you make to color and font settings are lost when you close
the configuration tool.
52 CICS Transaction Gateway: UNIX Administration

|
|
|
Configuration
The Help pulldown has the following options:
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” on page 241.
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 tree structure, 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 CICS Transaction Gateway settings
To display the Gateway 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 defined using the configuration tool is specified via the
associated command line option when the Gateway is started, the command
line setting takes precedence.
General Gateway settings
See Figure 11 on page 51 for the screen layout. The general Gateway settings
are:
Initial number of Connection Manager threads: Enter the initial number of
ConnectionManager threads. The default is 1.
Chapter 5. Configuration 53

|
|
|
|
|
|
|
|
Configuration
Set this to the normal number of JavaGateway objects opened by all
connected Java clients.
You can override this setting with the ctgstart -initconnect command.
Maximum number of Connection Manager threads: Enter the maximum
number of ConnectionManager threads. The default is 100.
This limits the maximum number of JavaGateway objects opened by all
connected Java clients. Set this to the maximum number of JavaGateway
objects that could be open at any one time from all the remotely-connected
Java clients.
You can override this setting with the ctgstart -maxconnect command.
If you select the Unrestricted checkbox, no limits are applied to the number of
ConnectionManager threads.
For information on threading limits, see Table 3 on page 17.
Initial number of Worker threads: Enter the initial number of Worker
threads. The default is 1.
Set this to the normal number of concurrent requests expected to be processed
concurrently by the CICS Transaction Gateway daemon.
You can override this setting with the ctgstart -initworker command.
Maximum number of Worker threads: Enter the maximum number of
Worker threads. The default is 100.
This limits the maximum number of parallel ECI, ESI and EPI requests that
the CICS Transaction Gateway can process. Set it to:
v Less than or equal to maxconnect (for single JavaGateway programs)
If you select the Unrestricted checkbox, no limits are applied to the number of
Worker threads.
You can override this setting with the ctgstart -maxworker command.
For information on threading limits, see Table 3 on page 17.
Enable reading input from console: Select this check box to enable the
reading of input from the console.
Reading of input from the console is enabled by default.
54 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You can override this setting with the ctgstart -noinput command.
Display TCP/IP hostnames: Select this check box to enable the display of
TCP/IP hostnames 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 hostnames in messages. This makes the
messages easier to read.
Note: Selecting this option might cause severe performance reduction on
some systems.
Let Java clients obtain generic ECI replies: Select this check box if you wish
Java clients 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.
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.
Configuration
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 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.
Chapter 5. Configuration 55

|
|
|
|
|
|
|
|
|
|
|
|
Configuration
v The same message qualifier can be used on an asynchronous call even if a
reply with that 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.
Log 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
client application program connects to, or disconnects from, the Gateway
daemon. The default is for these messages not to be written.
Timeout for in-progress requests to complete (ms): Enter a value in
milliseconds.
When a Java-client program disconnects from the Gateway, the Gateway may
still be processing requests on behalf of that program. If work is still in
progress, the ConnectionManager that was managing requests on behalf of
that Java-client waits for the requests to complete for up to the timeout
period. If there are still requests in progress after the timeout has expired, the
ConnectionManager continues its processing and marks itself as available for
use by a new connection. The default timeout is 10 000 milliseconds, but you
may enter a value to override the default.
If this value is set to zero, the ConnectionManager does not wait for
in-progress requests to complete.
Worker thread available timeout (ms): Enter a value in milliseconds.
When a ConnectionManager accepts a request, it must allocate a Worker
thread to execute that request. If a Worker does not become available within
the 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 is
immediately available.
56 CICS Transaction Gateway: UNIX Administration

Figure 12. TCP settings
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.
Port: Enter the TCP/IP port number.
The default port for TCP/IP is 2006.
You can override this setting with the ctgstart -port command.
Handler wakeup timeout (ms): Enter a value in milliseconds.
Configuration
This setting controls how frequently the protocol handler wakes from
accepting inbound connections. When it wakes, it checks to see whether the
Chapter 5. Configuration 57

Configuration
Gateway is being stopped, and so this value affects the time taken for the
Gateway to shutdown cleanly. If you set this value to zero then the handler
only wakes when a new connection is accepted, and so the Gateway will not
shutdown cleanly until that time.
Connection timeout (ms): Enter a value in milliseconds.
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,
then the connection is refused. If this value is set to zero, a connection is
refused if a ConnectionManager is not immediately available.
Idle timeout (ms): Enter a value in milliseconds.
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 connection is
disconnected, though if work is still in progress on behalf of the connection, it
may be left connected. If this value is not set, or is set to zero, then idle
connections will not be disconnected.
Cleanup processing will only result after a timeout if the server has support
for this function installed.
Ping time frequency (ms): Enter a value in milliseconds.
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 PONG response has not
been received by the time the next PING message is due to be sent, then the
connection is disconnected. Again, if work is still in progress on behalf of the
connection it may (depending on the drop working connections value setting)
be left connected. If this value is not set, or is set to zero, then PING messages
are not sent.
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.
SO_LINGER setting: Enter a SO_LINGER setting for any socket used by this
handler. The SO_LINGER setting specifies a delay value in seconds for closing
a socket. If this value is not entered, or set to zero, then SO_LINGER is
disabled for any sockets used by this protocol handler.
If SO_LINGER is enabled, and data transmission has not finished, a Close call
blocks the calling program until the data is transmitted or until the connection
58 CICS Transaction Gateway: UNIX Administration

times out. If SO_LINGER is disabled, a Close call 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.
Require clients to use security classes: Select this check box if you wish
your Gateway to accept only connections that use security classes.
When a Java-client program 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 12.
Configuration
Chapter 5. Configuration 59

Configuration
Figure 13. SSL settings
SSL protocol settings
Select the SSL subnode to display the settings for SSL. 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 either the
ssl: or https: 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
“Configuring your SSL clients” on page 98.
60 CICS Transaction Gateway: UNIX Administration

Configuration
KeyRing or Keystore name: Enter the server KeyRing classname for SSLight,
or the server KeyStore name for JSSE.
For a KeyStore, 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:
/mykeys/jsse/keystore.jks
\\mykeys\\jsse\\keystore.jks
The server KeyRing or KeyStore consists of a valid x.509 certificate that
identifies this server to connecting clients. This KeyRing or KeyStore is
generated using the SSL tools supplied with this product.
For more information about SSL and its associated KeyRings or KeyStores, see
Chapter 6, “Network Security” on page 93.
KeyRing or Keystore password: Enter the password that you specified for
the server KeyRing or KeyStore.
CICS Transaction Gateway writes the password to the configuration file in a
form that prevents a casual observer from easily reading it.
Chapter 5. Configuration 61

Configuration
Figure 14. HTTP settings
HTTP protocol settings
Select the HTTP subnode to display the settings for HTTP. The settings are
the same as for TCP.
The default port for HTTP is 8080.
62 CICS Transaction Gateway: UNIX Administration

Figure 15. HTTPS settings
HTTPS protocol settings
Configuration
Select the HTTPS subnode to display the settings for HTTPS. The settings are
the same as for HTTP except that HTTPS also has Use client authentication,
KeyRing or Keystore name, and KeyRing or Keystore password settings. See
“SSL protocol settings” on page 60 for details.
The default port for HTTPS is 443. However, on some operating systems,
processes require special privileges to access port numbers between 1 and
1024. If you plan to run CICS Transaction Gateway without these required
privileges, change the port number to a value greater than 1024.
Chapter 5. Configuration 63

|
|
|
|
|
|
|
|
|
|
|
|
|
Configuration
Figure 16. TCPAdmin settings
TCPAdmin protocol settings
Select the TCPAdmin subnode to display the settings for administration. The
settings are the same as for TCP except for the following:
v The default port is 2810
v There is no Require clients to use security classes field.
v TCPAdmin also has the following settings:
Max dedicated connections: Enter a value specifying the maximum number
of simultaneous dedicated client connections that can be made to the Gateway
administration handler.
Authorized Hosts: Enter a host name or IP address in the entry field. Click
Add to add the host to the Authorized Hosts list, below the entry field. Click
Remove to remove all selected hosts from the Authorized Hosts list.
64 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
Configuration
If there are entries in the Authorized Hosts list, only those hosts are allowed
to access the administration protocol handler. Be aware: If the list is empty, all
hosts are allowed access.
The default entry is 127.0.0.1, which represents the host on which the CICS
Transaction Gateway is installed. IP address 127.0.0.1 and the host name
localhost are considered to be different from the real IP address or host name
of the system.
For information about administering your system, see “Administering your
system” on page 135.
Chapter 5. Configuration 65

Configuration
Configuring Client settings
Figure 17. Client settings
Select the Client node to display the Client Settings panel. The settings map
to the parameters in the Client section of the CTG.INI file.
Default Server
Select the default server from the drop-down list.
Applid
Enter up to 8 characters, or leave this field with the default value of *.
This value specifies the applid of the CICS Universal Client 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.
66 CICS Transaction Gateway: UNIX Administration

Note: If the client is to be autoinstalled to more than one CICS server, and if
you enter a specific name for the applid, that name must be unique
with respect to all servers it is connected to. If the name is not unique,
then attempts to connect to a server may be rejected because another
client has already been installed using the same name. If a name of * is
used, the client may be known by a different unique name at each
server.
If the client is to communicate with a given server via SNA (AIX operating
system only), this applid may 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.
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 value does not include an overhead of 512 bytes needed by the
clients for some protocols.
Leave this setting at the default unless the CICS Transaction Gateway is
running on a machine that is short of memory.
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.
Maximum servers
Enter a value in the range 1 through 256. The default is 10.
This value specifies the maximum number of servers that can be accessed
concurrently from the client.
Maximum requests
Enter a value in the range 1 through 10 000. The default is 256.
Configuration
This value specifies the maximum number of concurrent items that may be
executing on the Client daemon, where an item is one of:
v a terminal emulator
Chapter 5. Configuration 67

Configuration
v an EPI 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 may be
less than this setting if other operating system limits (for example, memory
constraint or communication sessions), come into effect.
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.
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.
Note: This setting acts only as a default. The terminal and print emulators
provide options to override this value.
Codepage identifier override
Enter a value indicating a Coded Character Set Identifier (CCSID) to override
your local codepage identifier.
68 CICS Transaction Gateway: UNIX Administration

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 codepage 850 includes Euro support.
For codepage 1252, specify a CCSID value of 5348.
Notes:
1. Regardless of the value in the Codepage identifier override setting,
cicsterm always displays characters based on the local codepage of the
workstation.
2. If you use the CCSID to change the codepage identifier, data that is
already stored on the server may be modified when retrieved by the CICS
Transaction Gateway, if it includes characters for which the code points
produce different characters.
3. On AIX: 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
Codepage identifier override of 932, or add the statement ’CCSID=932’ to
the Client Section of the initialization file CTG.INI.
For more information on CCSIDs and data conversion, refer to Appendix A,
“Data conversion when using the Client daemon and a CICS server” on
page 225.
Server retry interval
Enter a number of seconds. This is 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.
Log file
Enter the name of the log file to be used for problem diagnosis.
Configuration
If not specified, the log filename defaults to CICSCLI.LOG in the /var/cicscli
subdirectory.
Chapter 5. Configuration 69

Configuration
Configuring Server settings
Figure 18. Server settings
Select a server in the tree structure to display the Server Settings panel. The
settings map to the parameters in a Server section of the CTG.INI file.
Server name
Enter a name of between 1 and 8 characters. This provides a
communications-protocol-independent name for the server, local to the Client
daemon.
Requests to access the server from ECI, EPI, ESI, or terminal emulators
reference the server through this name.
Description
Enter a description for the server of between 1 and 60 characters. This
description is optional.
70 CICS Transaction Gateway: UNIX Administration

The description is returned to applications running on the Client daemon by
the CICS_EpiListSystems and CICS_EciListSystems functions.
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 up to the first blank in the string are taken as the
transaction. The remaining data is passed to the transaction on its invocation.
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.
Use upper case security
Select this check box to specify that CICS Transaction Gateway converts to
uppercase any userid or password from an ECI application or from a user
prompt.
With this setting selected, you can enter userids and passwords in either
uppercase or lowercase. This setting is disabled by default.
Network protocol
Select from the drop-down list the protocol to be used for the server
connection:
v TCP/IP
v SNA (AIX operating system only)
v TCP62
Configuration
Protocol settings displayed on the panel change according to the protocol you
select.
Chapter 5. Configuration 71

Configuration
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 (hostname) or 192.113.36.200 (IP Address).
Hostnames are mapped to IP addresses either by the name server or in the
hosts system file. It is better to use a hostname in case the IP address
changes.
The hosts system file is in the /etc directory.
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.
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.
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.
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.
Send TCP/IP Keepalive packets: Select this check box if you want TCP/IP
to periodically send KeepAlive packets to the server to check the connection.
SNA settings
Note: SNA is only available on the AIX operating system
Use LU alias names: Select this check box to use LU alias names.
LU names are always aliases on AIX, so this setting is ignored.
72 CICS Transaction Gateway: UNIX Administration

|
|
|
|
Partner LU name: Enter the LU Name of the server as it is known to the
APPC configuration at the Client daemon.
This must be an eight-character alias name.
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.
This must be an eight-character alias name.
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, you must also update the
local hosts file. The path to the file is:
/etc/hosts
Configuration
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.
Multiple server definitions with identical combinations of Local LU, Partner
LU, and Mode name are not permitted in CTG.INI in the CICS Transaction
Gateway Version 5.0. This ensures that every connection that the CICS region
and the network protocol see is represented by a unique server definition in
Chapter 5. Configuration 73

|
|
|
|
Configuration
the configuration file. Existing Client applications that use different server
names to send requests to the same CICS region continue to work if a user
exit is defined to redirect requests. A sample user exit that does this is
provided; see /samples/samples.txt.
Partner LU name: Enter the LU Name of the server as it is known to the
SNA configuration at the client. This must be a qualified 17-character name,
for example, ABC3XYZ4.PQRS1234.
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.
If you enter a template, you must fill in the IP address mask for LU name
template (optional) field.
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.
To use a template you must configure your CICS server to install connections
dynamically.
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.
If several hundred clients are to use dynamic LU name generation to connect
to the CICS server, you should have more template replacement characters in
your Local LU name, for example, CTS8****. In fact, CICS Transaction Server
for z/OS uses the last four characters of the LU name as the connection name,
so these characters must be unique.
IP address mask for LU name template (optional): Enter an IP address mask
in big-endian, that is, most significant byte first order. This must be a
hexadecimal number, for example, FFFFFF80.
This address mask is used in dynamic LU name generation. 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.
74 CICS Transaction Gateway: UNIX Administration

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 to define the mode values specified for the Mode name
on your CICS server.
Common TCP62 settings
Configuration
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.
IP address mask for CP name (optional): Enter an IP address mask in
big-endian, that is, most significant byte first order. 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.
Chapter 5. Configuration 75

Configuration
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 hostname
LUA.NETID.sna.ibm.com to obtain the IP address of the node that has the LU
name NETID.LUA.
See “TCP62 settings” on page 73, for information on how IP addresses map to
host names.
TCP62 port: Enter a number between 0 and 65535 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.
On UNIX 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. You must also set the TCP62 port number on the CICS server
to the same value.
You must configure your CICS server with the same port number.
Remote node inactivity poll interval: Enter a number of seconds between 0
and 65535. The default value is 60 seconds. A value of 0 turns off polling.
This configuration setting controls the time that the Client daemon waits
before polling inactive connections.
The Client daemon polls inactive connections by sending MPTN keepalive
datagrams by User Datagram Protocol (UDP) to the CICS server. 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.
Advanced TCP62 settings
Maximum logical SNA sessions: Enter a value in the range 1 through 255.
The default value is 8.
This parameter defines the maximum number of logical SNA sessions
allowed. The number of concurrent transactions that can exist for a client is
76 CICS Transaction Gateway: UNIX Administration

estricted by the number of client contention winners available on the session.
For example, if the maximum number of sessions is 8, and the server has 1
contention winner, the client is left with 7 contention winners. This allows 7
concurrent transactions.
Maximum SNA RU size: Enter a value in the range 256 through 4096. You
are recommended to use the default value of 1024.
This parameter specifies the maximum size of the request or response units
sent over sessions.
SNA pacing size: Enter a value in the range 0 through 63. You are
recommended to use the default value of 8.
Configuration
This parameter specifies how many request units can be sent before receiving
a pacing response.
Chapter 5. Configuration 77

|
|
|
|
|
|
|
|
|
|
|
Configuration
Trace settings
To configure the trace settings, select the Trace Settings option from the Tools
menu.
Trace Settings
Select check boxes to specify the CICS Transaction Gateway and Client
daemon components that will be traced when tracing is turned on.
Trace everything
All 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.
Gateway
The CICS Transaction Gateway.
JNI Trace
You cannot enable JNI trace through the configuration tool. Use one of
the following methods to enable it:
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.
v While the CICS Transaction Gateway is running, use the system
administration functions. You must have enabled the TCPAdmin
protocol handler (see “TCPAdmin protocol settings” on page 64). See
“Administering your system” on page 135 for details of how to enable
JNI trace dynamically.
78 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
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
Using the CTG_JNI_TRACE environment variable to enable JNI trace is
supported only for migration purposes.
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 option with 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 139.
If you turn on tracing without specifying the components in either the cicscli
command or in CTG.INI, a default set of components is traced:
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.
Gateway trace file
Enter the pathname of a trace file to which trace messages will be written, if
tracing is enabled. If no path is specified, the trace is written as follows:
/bin/CTG.TRC
You can also specify a trace file using the tfile option on the ctgstart
command.
Configuration
The trace file is overwritten (not appended to) each time the CICS Transaction
Gateway starts.
Chapter 5. Configuration 79

Configuration
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.
Gateway trace wrap size
Enter a value in the range 0 through 1 000 000 kilobytes.
This value specifies the size in kilobytes to which the gateway trace file will
grow. Subsequent trace entries will continue to be written from the beginning
of the file. The default value of 0 disables wrapping.
Client trace file
Enter the pathname of a trace file to which trace messages will be written, if
tracing is enabled.
You do not have to enter an extension for the filename, as 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:
/var/cicscli/CICSCLI.BIN
To minimise 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 185.
Maximum Client wrap size
Enter a value in the range 0 through 65 535 KB.
This value specifies how large the trace file will grow on disk before
wrapping. The default value of 0 disables wrapping.
Editing the configuration file
Although it is recommended that you use the configuration tool you can edit
the configuration file direct.
The configuration file has the following sections:
1. GATEWAY
2. CLIENT
3. SERVER
4. DRIVER
80 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
For information on the properties in each section, refer to the descriptions of
the corresponding settings in the configuration tool.
The DRIVER section has no corresponding section in the configuration tool.
The configuration tool automatically selects the correct protocol drivers.
Each section has the format:
SECTION sectioname [=value]
# Comment describing the section
property1=value
property2=value
...
propertyN=value
ENDSECTION
Note: If you use the # 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.
J2EE setup and configuration
Configuration
This topic discusses the administration of CICS resource adapters. Two
resource adapters are supplied with the CICS Transaction Gateway. The
/deployable directory contains an adapter for ECI (cicseci.rar),
and one for EPI (cicsepi.rar).
Any value set by the setExecuteTimeout method of the ECIInteractionSpec
class is ignored; neither connector supports timeout. An alternative is to set
the TIMEOUT parameter in the external CICS interface options table,
DFHXCOPT. See the CICS External Interfaces Guide for more information.
Deploying CICS resource adapters
Before you can use a J2EE resource adapter in a server runtime environment
you must supply parameters for its internal ManagedConnectionFactory class.
In a managed environment you set these parameters when you deploy the
resource adapter to your server. For instructions on how to do this consult
your server’s documentation.
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.
Chapter 5. Configuration 81

Deployment parameters for the ECI resource adapter
Deployment parameters for the ECI resource adapter
This section describes the available deployment parameters for the ECI
resource adapter, and their effect on the final deployed resource adapter. The
tools used to configure these parameters are server-specific. Not all
parameters are required; the default value is shown where appropriate.
ConnectionURL
The URL of the CICS Transaction Gateway with which the resource
adapter will communicate. The URL takes the form
protocol://address. These protocols are available:
v tcp
v http
v ssl
v local
So, for example, you might specify a URL of tcp://ctg.business.com.
For the local protocol simply specify local:.
PortNumber
The port to connect to where the CICS Transaction Gateway is
running. 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. This is the name as defined in the CICS
Transaction Gateway configuration file. To use multiple servers within
an environment you must deploy several resource adapters, each with
a different ServerName attribute set.
TranName
The name of the CICS Transaction under which you want all
programs started by the resource adapter to run.
TPNName
The name of the CICS TPN Transaction under which you want all
programs started by the resource adapter to run. Note that TPNName
takes precedence if both TranName and TPNName are specified.
UserName
The CICS userid to be used if no other security credentials are
available. See the J2EE section in the CICS Transaction Gateway:
Programming Guide for more information.
Password
The password for the CICS userid 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
82 CICS Transaction Gateway: UNIX Administration

Deployment parameters for the ECI resource adapter
then 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
then 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 keyring class to use. This only
applies when using the SSL protocol.
KeyRingPassword
The password for the class 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 86.
As well as these user-definable properties, the ECI 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 ECI resource adapter is defined as LocalTransaction. If your
server supports LastResourceOptimization, the resource adapter can
participate in a global transaction, provided it is the only
LocalTransaction resource that has been enlisted.
Re-Authentication Support
The ECI 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.
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. Not all of these
parameters are required; the default value is shown where appropriate.
ConnectionURL
The URL of the CICS Transaction Gateway with which the resource
Chapter 5. Configuration 83

Deployment parameters for the EPI resource adapter
adapter will communicate. The URL takes the form
protocol://address. These protocols are available:
v tcp
v http
v ssl
v local
So, for example, you might specify a URL of tcp://ctg.business.com.
For the local protocol simply specify local:.
PortNumber
The port to connect to where the CICS Transaction Gateway is
running. 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. This is the name as defined in the CICS
Transaction Gateway configuration file. To use multiple servers within
an environment you must deploy several resource adapters, each with
a different ServerName attribute set.
UserName
The CICS userid 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 signon capable, or
v The CICS Server does not support signon capable terminals (for
example, CICS for OS/2)
Password
The password for the CICS userid 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
then 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
then no ServerSecurity class is used. For more information on what
ServerSecurity classes are used for, and how to write them, see CICS
84 CICS Transaction Gateway: UNIX Administration

Deployment parameters for the EPI resource adapter
Transaction Gateway security classes in the Java chapter of the CICS
Transaction Gateway Programming Guide.
KeyRingClass
The fully qualified name of the SSL keyring class to use. This only
applies when using the SSL protocol.
KeyRingPassword
The password for the class 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 terminals
on CICS that are used by the resource adapter are signon capable or
incapable. Acceptable values are:
v 0 — Signon capable terminal (default)
v 1 — Signon incapable terminal
Encoding
The Java Encoding to use when creating 3270 datastreams. The
encoding will be converted to the appropriate CCSid. See the
appendix in the CICS Transaction Gateway: Programming Reference
manual for a list of supported encodings. Ensure that your CICS
Server supports the CCSid from the given encoding.
LogonLogoffClass
The fully qualified name of the Java Class that provides the logic to
Logon to a CICS Server using signon transactions. This property is
mandatory for signon capable terminals and for CICS servers that do
not support signon capability (such as CICS for OS/2).
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.
Chapter 5. Configuration 85

Deployment parameters for the EPI resource adapter
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 signon
capable terminals (such as CICS for OS/2).
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.
86 CICS Transaction Gateway: UNIX Administration

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.
Control of where trace is output is handled by the ConnectionManager being
used by your environment. 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 may 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.
Sample configuration and mapping files
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. (A sample file
CICSKEYSAMP.INI is also provided.)
CICSCOL.INI The color mapping file. (A sample file
CICSCOLSAMP.INI is also provided.)
It is recommended that you create your own customized versions of these
files with different names, because installation of service updates may
overwrite the files and cause any customization to be lost.
Tracing
Reference your customized files through the following environment variables:
File Environment variable
configuration file CICSCLI
Chapter 5. Configuration 87

Sample configuration and mapping files
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” on
page 87 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 page “Keyboard mapping for
cicsterm”).
v The CICSKEY environment variable. For example:
export CICSKEY=/var/cicscli/MYKEYS.INI
If you do not specify otherwise, a filename 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:
Keyboard mapping file syntax
►► BIND 3270function
modifier+
key
; 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:
88 CICS Transaction Gateway: UNIX Administration
►◄

ackspace 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
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:
Ctrl
Shift
The Key can be any one of the keys shown in Table 8, (but some combinations
of modifier+key are not supported — see “Key combinations” on page 90):
Table 8. 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
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* keypadkeypad7
keypad8 keypad9
keypad4 keypad5 keypad6 keypad+
keypad1 keypad2 keypad3
keypad0 keypad. keypadenter
Keyboard mapping for cicsterm
Chapter 5. Configuration 89

Keyboard mapping for cicsterm
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 87 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 page “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 filename 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.
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.
Notes:
1. If the color mapping file specifies a mapping for an attribute, this mapping
is used even if the hardware upon which the client is running actually
supports the screen attribute.
90 CICS Transaction Gateway: UNIX Administration

2. 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, then the field is displayed without any
highlighting at all.
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:
Color mapping file syntax
►► BIND 3270attrib fg_color
/bg_color ; 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
Each of fg_color and bg_color (foreground color and background color) can be
any one of the following:
black light_gray
blue light_blue
brown yellow
cyan light_cyan
green light_green
magenta light_magenta
red light_red
gray white
Customizing the screen colors for cicsterm
If bg_color is omitted, a default value of black is taken.
►◄
Chapter 5. Configuration 91

|
|
|
Preparing to use local CICS Transaction Gateway support
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 correctly configured your
environment. The following are required:
1. A correctly configured Java environment
AIX:
Use a shell command like the following to add the /bin
subdirectory to your LIBPATH:
export LIBPATH=/bin:${LIBPATH}
Other UNIX operating systems:
A Java application that uses the local CICS Transaction Gateway support
is a normal Java program, and so is executed with the standard JDK Java
executable. Your environment must be correctly set so that the Java
binaries, libraries, and classes can be found. Refer to the JDK
documentation for the correct environment settings.
2. The correct settings to allow the CICS Transaction Gateway binaries to
be found
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. Also, the relevant
binaries must be available.
On Linux and Solaris, set your LD_LIBRARY_PATH environment variable to
include the /bin subdirectory so that your application can
find libCTGJNI.so.
On HP-UX set your SHLIB_PATH environment variable to include the
/bin subdirectory so that your application can find
libCTGJNI.so.
On AIX, set your PATH environment variable to include the
/bin subdirectory, so that the cicsjava script can be called
easily.
To run the application: use the JDK java command with suitable options.
92 CICS Transaction Gateway: UNIX Administration

Chapter 6. Network Security
This chapter describes how to set up CICS Transaction Gateway to use the
network security protocols SSL and HTTPS. This chapter consists of the
following:
“Determining your use of SSLight or JSSE
for the SSL and HTTPS protocols” on
page 94
“Maintaining your digital certificates for
SSLight” on page 94
“Using externally signed certificates
under SSLight” on page 95
“Using self-signed certificates under
SSLight” on page 100
Read this for information on how CICS
Transaction Gateway determines whether
you are using SSLight or JSSE.
Read this for information on using the
IBM Key Management utility iKeyMan
for managing your digital certificates for
SSLight.
Read this for information on how to
configure an SSL server and SSL clients to
use externally signed digital certificates
under SSLight.
Read this for information on how to
configure an SSL server and SSL clients to
use self-signed digital certificates under
SSLight.
“Migration from SSLight” on page 104 Read this for information on migrating
from SSLight to JSSE.
“Installation” on page 104 Read this for information on installing
JSSE.
“Maintaining your digital certificates for
JSSE” on page 105
“Using externally signed certificates
under JSSE” on page 105
“Using self-signed certificates under JSSE”
on page 110
“Configuring CICS Transaction Gateway
for SSL and HTTPS” on page 114
Read this for information on using the
IBM Key Management utility iKeyMan
for managing your digital certificates for
JSSE.
Read this for information on how to
configure an SSL server and SSL clients to
use externally signed digital certificates
under JSSE.
Read this for information on how to
configure an SSL server and SSL clients to
use self-signed digital certificates under
JSSE.
Read this for information on how to
configure CICS Transaction Gateway to
use the secure protocols.
© Copyright IBM Corp. 1996, 2002 93

|
|
Security
Determining your use of SSLight or JSSE for the SSL and HTTPS protocols
SSLight
CICS Transaction Gateway determines whether you wish to use SSLight or
JSSE as follows:
v If you pass a KeyRing class to the Gateway daemon, CICS Transaction
Gateway assumes that you are using SSLight.
v If you pass a KeyStore file to the Gateway daemon, CICS Transaction
Gateway assumes that you are using JSSE.
Conflict with JSSE
SSLight might not function correctly if JSSE is installed on your system. If
JSSE is installed, rename file gskikm.jar, intheJRE/EXT directory.
Maintaining your digital certificates for SSLight
iKeyMan
Use the ctgikey command to invoke iKeyMan for certificate management.
With iKeyMan, you can:
v Request and receive a digital certificate from a Certification Authority (CA),
see “Using externally signed certificates under SSLight” on page 95.
v Generate self-signed certificates, see “Using self-signed certificates under
SSLight” on page 100.
v Add certificates to your KeyRing files.
v Change your KeyRing 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 KeyRing.
Distributing iKeyMan to client workstations
Although you perform most of the KeyRing management on the CICS
Transaction Gateway machine, you might need to distribute the iKeyMan tool
to clients connecting to your SSL server. The client machines must have the
minimum level of CICS Transaction Gateway Java support; see “Supported
software” on page 23. They might also require a script or command file to
invoke the iKeyMan Java startup class.
The following is an example of a command that you can use to invoke
iKeyMan with the JDK or the JRE:
94 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
Maintaining your digital certificates for SSLight
java -classpath
"/cfwk.zip;/gsk5cls.jar;"
-Dkeyman.javaOnly=true com.ibm.gsk.ikeyman.Ikeyman
Where is the directory where ikeyman is installed.
These examples assume that the client workstation has the following files in
the ikeyman directory:
v cfwk.zip
v cfwk.sec
v gsk5cls.jar
v ikminit.properties
All of these files are in the /classes subdirectory.
Using iKeyman in DBCS environments
If you have trouble running iKeyman in your locale, you can use this
command to run it in English:
java -classpath "/classes/cfwk.zip:
/classes/gsk5cls.jar:"
-Dkeyman.javaOnly=true
-Dkeyman.lang=en_US com.ibm.gsk.ikeyman.Ikeyman
Using externally signed certificates under SSLight
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. The following sections
describe how to configure an SSL server and SSL clients using iKeyMan.
Configuring your SSL server and clients involves:
1. Creating a KeyRing class
2. Creating a certificate request
3. Obtaining a digital certificate
4. Receiving the digital certificate into the KeyRing
Configuring your SSL server
This section describes how to obtain a Test Server Certificate from the
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a
period of 14 days. As this certificate is for demonstration only it is not signed
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All
SSL clients need the VeriSign Test signer certificate root key to be installed in
their client KeyRings, or, in the case of HTTPS connections, the repository in
the browser. Obtaining a full VeriSign Server Certificate follows the same
procedures as described here for the test version.
1. Create a server KeyRing
Chapter 6. Network Security 95

Using externally signed certificates under SSLight
The first step is to create a server KeyRing class. This will contain 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 using the command ctgikey.
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyServerKeyRing.class
e. In Location, type a suitable location to store your server KeyRing
The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing 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 MyServerKeyRing.class contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 98.
2. Create a Certificate Request
Before you can obtain a Server Certificate from VeriSign, you must make a
Certificate Request and store it locally:
a. From iKeyMan, select Create —> New Certificate Request.
b. Complete the certificate request. Some fields are optional, but you must
fill in at least the following (examples are shown):
Key Label verisignServerCert
96 CICS Transaction Gateway: UNIX Administration

Using externally signed certificates under SSLight
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
c. Specify the name of a file in which to store the certificate request, or
accept the default.
d. Select OK.
iKeyMan generates a public/private key pair.
3. Obtain a Server Certificate
The next step is to connect to the VeriSign Web site and request a Test
Server Certificate:
a. Point your Web browser at: www.verisign.com and navigate to their
request Test Server Certificate application pages.
b. Open the certificate request file you created earlier, using an ASCII text
editor.
Figure 19 on page 98 shows an example of a certificate request.
c. During the Test Server Certificate request process you will be asked to
submit your CSR — Copy and paste the contents of the file into the
text box in the Web page.
d. Verify the contents of your certificate request and provide the personal
details when requested.
If you are requesting a full VeriSign Server ID, rather than a test
version, these details are used to authenticate your application.
e. VeriSign processes your enrollment and sends an e-mail to the address
specified in your personal details.
This e-mail contains your Test Server Certificate, and instructions on
how to:
v install a Test Server ID
v install a special Test CA Root
Chapter 6. Network Security 97

Using externally signed certificates under SSLight
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIB1jCCAT8CAQAwgZUxIDAeBgNVBAMTF2NocmlzdHAuaHVyc2xleS5pYm0u
Y29tMRswGQYDVQQLExJDbGllbnRzICsgR2F0ZXdheXMxDzANBgNVBAoTBklC
TSBVSzETMBEGA1UEBxMKV0luY2hlc3RlcjEOMAwGA1UECBMFSGFudHMxETAP
BgNVBBETCFNPMjEgMkpOMQswCQYDVQQGEwJHQjCBnzANBgkqhkiG9w0BAQEF
AAOBjQAwgYkCgYEAkAth9Ar6k6ijNZ3JxdPGH6yiikwYTuA0RZDLZBSpaSEx
4qNKN/CrdF1LgfQYbZcN5NGCeC4sC478NhT+ltf5dnR3pNWBzEzmWn5mN0lH
tqJ3oibOUmDui+tQc2J9z6iRBKjkcQwjPlJp0sp5KKsev1ahAETL7LqmqMIq
pJlzKi0CAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GBAHaMHpizPs8Q3bi3I6dh
4yw0UNhojTlS1+ffiph3hK98lMHJuMztr0UMBLl/SZGNw85OJRiWuDjGYUQW
inJ0uNH34IUsnygBmt78+WlXT5nJuayg+UrAc5Ao2H8QZpRE5Sfaoc8lQcvY
plTggCdMxpYN7I33LrZDl3Po0TT8gjxQ
-----END NEW CERTIFICATE REQUEST-----
Figure 19. Example certificate request
4. Receive the Server Certificate into the server KeyRing
When you have obtained the Server Certificate, you use iKeyMan to
receive it into the server KeyRing.
a. Copy and paste the Server Certificate data into a blank text file, using
an ASCII text editor; save the file as verisignServerID.arm.
b. From iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
c. Select Receive...
d. In the Data type pull-down, select Base64-encoded ASCII
e. Type the name and location of the text file containing your Server
Certificate data
f. Select OK.
g. Select Key Database File then Exit.
Your server KeyRing MyServerKeyRing.class is now ready for use with
CICS Transaction Gateway. It contains the default signer certificates, as
well as your VeriSign Server Certificate and its corresponding private key.
Configuring your SSL clients
In normal operation, CICS Transaction Gateway uses only server
authentication when performing an SSL handshake; the client need only
accept the presented Server Certificate. For server authentication to work, the
client KeyRing class, or in the case of HTTPS, the browser certificate
repository, must contain the signer certificate of the Server Certificate. In our
example, the signer certificate is the VeriSign Test signer certificate.
In addition to server authentication, the CICS Transaction Gateway also
supports client authentication. With this option enabled, any connection
attempted to either the ssl: or https: handler requires the client to present its
own Client Certificate, which is also known as a Digital ID.
The following sections describes how to obtain a VeriSign Digital ID.
98 CICS Transaction Gateway: UNIX Administration

Using externally signed certificates under SSLight
1. Create a client KeyRing
A client KeyRing class 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 KeyRing class is similar to that for a
server:
a. Start iKeyMan using the command ctgikey
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyClientKeyRing.class
e. In Location, type a suitable location to store your client KeyRing
The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
h. Select OK.
Like the server KeyRing class, the client KeyRing class contains a default
selection of popular signer certificates.
2. Obtain a Client Certificate
Unlike Server Certificates, you do not need to create a certificate request to
obtain a Client Certificate. VeriSign provides a method of obtaining a Class
1 Digital ID using either Netscape or Internet Explorer browsers.
When you have obtained the Client Certificate and installed it in the
browser repository, you can export the certificate data, together with its
associated private key, into a secure file known as a #PKCS12 file. This file
is password protected and can be imported into a client KeyRing class
using the iKeyMan tool.
a. Point your Web browser at: www.verisign.com
b. Follow the links on their Web site to buy a Class 1 Digital ID from
their Secure E-Mail certificates product area.
c. Complete the enrollment form as requested. The details will be used by
VeriSign to authenticate the client application.
d. VeriSign will send information for downloading and installing the
Class 1 Digital ID to the e-mail address you supplied in your
application.
During the installation process, your browser allows you to store the
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool
supports #PKCS12 files and allows you to import certificates, along with
their private key, into a client KeyRing class.
3. Import the Client Certificate into the client KeyRing
To import the #PKCS12 file containing the Client Certificate:
Chapter 6. Network Security 99

Using externally signed certificates under SSLight
a. In iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
b. Select Import...
c. Set Key file type to PKCS12 file.
d. Type the name and location of the #PKCS12
e. Select OK.
f. Select Key Database File —> Close
g. Select Key Database File —> Exit
Your client KeyRing MyClientKeyRing.class is now ready for use with CICS
Transaction Gateway. It contains the default signer certificate, as well as your
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding
private-key.
Using self-signed certificates under SSLight
CICS Transaction Gateway provides a way for you to “self-sign” your
certificates. You establish yourself as your own Certification 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 KeyRing classes
2. creating digital certificates
3. exporting and importing the certificates
Configuring your SSL server
1. Create a server KeyRing
The first step is to create a server KeyRing class. This will contain 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 using the command ctgikey.
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyServerKeyRing.class
e. In Location, type a suitable location to store your server KeyRing
The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
100 CICS Transaction Gateway: UNIX Administration

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 MyServerKeyRing.class contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
Using self-signed certificates under SSLight
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 98.
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 KeyRing class:
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.
Chapter 6. Network Security 101

Using self-signed certificates under SSLight
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, 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 handshake with this SSL server.
Configuring your SSL clients
1. Create a client KeyRing
A client KeyRing class 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 KeyRing class is similar to that for a
server:
a. Start iKeyMan using the command ctgikey
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyClientKeyRing.class
e. In Location, type a suitable location to store your client KeyRing
The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
h. Select OK.
Like the server KeyRing class, the client KeyRing class contains a default
selection of popular signer certificates.
2. Import the server’s signer certificate
a. In iKeyMan select Add
102 CICS Transaction Gateway: UNIX Administration

Using self-signed certificates under SSLight
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.
If the SSL handler used by the CICS Transaction Gateway is configured to
support only server authentication, skip step 3; the client KeyRing need
contain only the signer certificate of the Server, which you have now
imported. You can use the generated MyClientKeyRing.class file with
CICS Transaction Gateway’s SSL protocol, which is configured to support
server authentication.
3. Create a Client Certificate
Client authentication requires the client KeyRing class 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. 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
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
Chapter 6. Network Security 103

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under SSLight
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 handshake 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 KeyRing class files, created with Version 3.0,
using the iKeyMan tool.
Restricting access to the server KeyRing
The contents of the server KeyRing are encrypted and protected by a
password. However IBM recommends that you:
v ensure that the KeyRing class files have appropriate security access
permissions
v restrict access, where applicable, to the CICS Transaction Gateway machine
Do not share certificates among servers. Do not allow servers to share a
private key, particularly if they are running on different machines. Never send
a private key to someone else.
Java Secure Socket Extension (JSSE)
Migration from SSLight
To avoid possible conflicts between the different versions of iKeyMan used in
SSLight and JSSE, IBM strongly recommends that you perform all migration
actions before you install JSSE.
To migrate from SSLight to JSSE:
v Create new KeyStores and use these instead of existing KeyRing classes
v Change existing security exits that implement the SSLightServerSecurity
interface to implement the JSSEServerSecurity interface
Installation
See “Supported software” on page 23 for details of environments in which
JSSE is supported.
If you do not have a supported level of JSSE on your system, you need to
install the version supplied with CICS Transaction Gateway. JSSE support is
included in two zip files supplied with the CICS Transaction Gateway
product:
104 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
v ibm-jsse.zip
v ibm-jce.zip
Copy the zip files to the jre subdirectory of your Java installation directory
on your system, and extract the archived files into this directory.
The Java root directory is the directory which has jre as a subdirectory.
On HP-UX and Solaris, you might need to update the
lib/security/java.security file. In this file, locate the lines which begin
security.provider and add a line like the following if it does not already
exist:
security.provider.=com.ibm.crypto.provider.IBMJCE
where is the next number in sequence following any existing entries.
Maintaining your digital certificates for JSSE
iKeyMan
Use the following command to start the iKeyMan program:
java com.ibm.ikeyman.Ikeyman
With iKeyMan, you can:
v Request and receive a digital certificate from a Certification Authority (CA),
see “Using externally signed certificates under SSLight” on page 95.
v Generate self-signed certificates, see “Using self-signed certificates under
SSLight” on page 100.
v Add certificates to your KeyStore files.
v Change your KeyStore 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 KeyStore.
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. The following sections
describe how to configure an SSL server and SSL clients using iKeyMan.
Configuring your SSL server and clients involves:
1. Creating a KeyStore
2. Creating a certificate request
Installing JSSE
Chapter 6. Network Security 105

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
3. Obtaining a digital certificate
4. Receiving the digital certificate into the KeyStore
Configuring your SSL server
This section describes how to obtain a Test Server Certificate from the
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a
period of 14 days. As this certificate is for demonstration only it is not signed
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All
SSL clients need the VeriSign Test signer certificate root key to be installed in
their client KeyStores, or, in the case of HTTPS connections, the repository in
the browser. Obtaining a full VeriSign Server Certificate follows the same
procedures as described here for the test version.
1. Create a server KeyStore
The first step is to create a server KeyStore. This will contain 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 KeyStore, such as
MyServerKeyStore.jks
e. In Location, type a suitable location to store your server KeyStore
f. Select OK
g. Type a password for the KeyStore 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 MyServerKeyStore.jks contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
106 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 108.
2. Create a Certificate Request
Before you can obtain a Server Certificate from VeriSign, you must make a
Certificate Request and store it locally:
a. From iKeyMan, select Create —> New Certificate Request.
b. Complete the certificate request. Some fields are optional, but you must
fill in at least the following (examples are shown):
Key Label verisignServerCert
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
c. Specify the name of a file in which to store the certificate request, or
accept the default.
d. Select OK.
iKeyMan generates a public/private key pair.
3. Obtain a Server Certificate
The next step is to connect to the VeriSign Web site (www.verisign.com)
and request a Test Server Certificate. You will be asked to paste in the
contents of the certificate request file you created earlier (Figure 19 on
page 98 shows an example of a certificate request) and agree to their
licensing conditions. VeriSign will then send you a confirmation e-mail.
This e-mail contains your Test Server Certificate, and instructions on how
to:
v install a Test Server ID
v install a special Test CA Root
Chapter 6. Network Security 107

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
4. Receive the Server Certificate into the server KeyStore
When you have obtained the Server Certificate, you use iKeyMan to
receive it into the server KeyStore.
a. Copy and paste the Server Certificate data into a blank text file, using
an ASCII text editor; save the file as verisignServerID.arm.
b. From iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
c. Select Receive...
d. In the Data type pull-down, select Base64-encoded ASCII
e. Type the name and location of the text file containing your Server
Certificate data
f. Select OK.
g. Select Key Database File then Exit.
Your server KeyStore MyServerKeyStore.jks is now ready for use with
CICS Transaction Gateway. It contains the default signer certificates, as
well as your VeriSign Server Certificate and its corresponding private key.
Configuring your SSL clients
In normal operation, CICS Transaction Gateway uses only server
authentication when performing an SSL handshake; the client need only
accept the presented Server Certificate. For server authentication to work, the
client KeyStore, or in the case of HTTPS, the browser certificate repository,
must contain the signer certificate of the Server Certificate. In our example,
the signer certificate is the VeriSign Test signer certificate.
In addition to server authentication, the CICS Transaction Gateway also
supports client authentication. With this option enabled, any connection
attempted to either the ssl: or https: handler requires the client to present its
own Client Certificate, which is also known as a Digital ID.
The following instructions describe how to obtain a VeriSign Digital ID.
1. Create a client KeyStore
A client KeyStore class 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 KeyStore class 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 KeyStore, such as
MyClientKeyStore.jks
e. In Location, type a suitable location to store your client KeyStore
108 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
f. Select OK
g. Type a password for the KeyStore file.
h. Select OK
Like the server KeyStore, the client KeyStore contains a default selection of
popular signer certificates.
2. Obtain a Client Certificate
Unlike Server Certificates, you do not need to create a certificate request to
obtain a Client Certificate. VeriSign provides a method of obtaining a Class
1 Digital ID using either Netscape or Internet Explorer browsers.
When you have obtained the Client Certificate and installed it in the
browser repository, you can export the certificate data, together with its
associated private key, into a secure file known as a #PKCS12 file. This file
is password protected and can be imported into a client KeyStore using
the iKeyMan tool.
a. Point your Web browser at: www.verisign.com
b. Follow the links on their Web site to buy a Class 1 Digital ID from
their Secure E-Mail certificates product area.
c. Complete the enrollment form as requested. The details will be used by
VeriSign to authenticate the client application.
d. VeriSign will send information for downloading and installing the
Class 1 Digital ID to the e-mail address you supplied in your
application.
During the installation process, your browser allows you to store the
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool
supports #PKCS12 files and allows you to import certificates, along with
their private key, into a client KeyStore.
3. Import the Client Certificate into the client KeyStore
To import the #PKCS12 file containing the Client Certificate:
a. In iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
b. Select Import...
c. Set Key file type to PKCS12 file.
d. Type the name and location of the #PKCS12
e. Select OK.
f. Select Key Database File —> Close
g. Select Key Database File —> Exit
Chapter 6. Network Security 109

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
Your client KeyStore MyClientKeyStore.jks is now ready for use with CICS
Transaction Gateway. It contains the default signer certificate, as well as your
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding
private-key.
Using self-signed certificates under JSSE
CICS Transaction Gateway provides a way for you to “self-sign” your
certificates. You establish yourself as your own Certification 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 KeyStores
2. creating digital certificates
3. exporting and importing the certificates
Configuring your SSL server
1. Create a server KeyStore
The first step is to create a server KeyStore. This will contain 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 KeyStore, such as
MyServerKeyStore.jks
e. In Location, type a suitable location to store your server KeyStore
f. Select OK
g. Type a password for the KeyStore 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 MyServerKeyStore.jks contains, by default, a selection
of popular signer certificates as follows:
110 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
Using self-signed certificates under JSSE
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 108.
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 KeyStore:
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
Chapter 6. Network Security 111

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
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, 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 handshake with this SSL server.
Configuring your SSL clients
1. Create a client KeyStore
A client KeyStore class 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 KeyStore class 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 KeyStore, such as
MyClientKeyStore.jks
e. In Location, type a suitable location to store your client KeyStore
f. Select OK
g. Type a password for the KeyStore file.
h. Select OK
Like the server KeyStore, the client KeyStore 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.
112 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
If the SSL handler used by the CICS Transaction Gateway is configured to
support only server authentication, skip step 3; the client KeyStore need
contain only the signer certificate of the Server, which you have now
imported. You can use the generated MyClientKeyStore.jks file with CICS
Transaction Gateway’s SSL protocol, which is configured to support server
authentication.
3. Create a Client Certificate
Client authentication requires the client KeyStore 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. 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
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 handshake with this SSL client.
Chapter 6. Network Security 113

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
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 KeyStore files, created with Version 3.0, using the
iKeyMan tool.
Restricting access to the server KeyStore
The contents of the server KeyStore are encrypted and protected by a
password. However IBM recommends that you:
v ensure that the KeyStore files have appropriate security access permissions
v restrict access, where applicable, to the CICS Transaction Gateway machine
Do not share certificates among servers. Do not allow servers to share a
private key, particularly if they are running on different machines. Never send
a private key to someone else.
Configuring CICS Transaction Gateway for SSL and HTTPS
To use the SSL and HTTPS protocols, enable them using the configuration
tool; see “Configuring CICS Transaction Gateway settings” on page 53. You
can specify that either or both of the protocols is used. When you enable the
protocols, by default, CICS Transaction Gateway listens for SSL requests on
port 8050, and for HTTPS requests on port 443.
SSL and HTTPS configuration settings
The following configuration settings are specific to the SSL and HTTPS
protocols:
KeyRing or KeyStore name Specifies the name of the server KeyRing or
KeyStore.
For a KeyRing, you must also add the
classname to the CLASSPATH environment
variable.
KeyRing or KeyStore password
Specifies the password used to read the
encrypted server KeyRing or KeyStore.
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 Enables client authentication. The default is
that only server authentication is enabled.
114 CICS Transaction Gateway: UNIX Administration

Configuring CICS Transaction Gateway for SSL and HTTPS
CICS Transaction Gateway provides two default KeyRing class files,
ClientKeyRing and ServerKeyRing, that you can use to establish SSL and HTTPS
connections under SSLight. Both KeyRings have been encrypted using the
password default. Use them only in testing environments.
Specifying a client KeyRing or KeyStore
Your choice of secure protocol determines whether or not you need a
KeyRing, or KeyStore, for both server and client:
HTTPS
Specify a KeyRing or KeyStore only in the server.
SSL
The SSL protocol requires you to specify KeyRings, or KeyStores for both the
server and the client.
For more information see SSL JavaGateway, inCICS Transaction Gateway:
Programming Guide.
Using the SSL and HTTPS protocols
You use the SSL and HTTPS protocols in a similar way to the TCP and HTTP
protocols. To make a connection to CICS Transaction Gateway, your client
application flows a request using the appropriate URL. For example, for SSL
use a URL like:
ssl://transGatewayMachine:8050
Similarly, for HTTPS:
https://transGatewayMachine:443
For more information on the design and implementation of client-side
programs, see CICS Transaction Gateway: Programming Guide, and the CICS
Transaction Gateway programming interface HTML pages.
Chapter 6. Network Security 115

116 CICS Transaction Gateway: UNIX Administration

Chapter 7. Client Security
Overview
This chapter describes how to provide a userid and password when
connecting to a CICS server. It consists of the following:
“Overview” Read this for an overview of CICS
client/server security.
“Default connection settings” on page 118 Read this for information on setting
default values for userid and password.
“ECI security” on page 118 Read this for information on providing a
userid and password on an ECI request.
“EPI terminal security” on page 118 Read this for information on providing a
userid and password on an EPI request.
“Signon capable and signon incapable
terminals” on page 120
Read this for information on signon
capable and signon incapable terminals.
CICS servers may require the Client daemon to supply a userid 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 userid and
password are sent to the server in the FMH header of the transaction attach
request for each conversation. A userid and password are also required when
a signon transaction is invoked on a signon capable terminal. In this instance,
the userid and password are flowed to the server as part of the 3270
datastream.
Because the Client daemon has no security manager, it does not support
userid authentication. It is recommended that you configure your CICS server
client connections so that incoming attach requests must specify a userid and
password. For mainframe servers, specify AttachSec = Verify in the CICS
connection definition. AttachSec = Identify, which indicates that userid, but
not password, are required, is not supported for client connections.
Note: Userids and passwords must not contain DBCS characters.
© Copyright IBM Corp. 1996, 2002 117

Client Security
Default connection settings
ECI security
The Client daemon maintains a default userid and password for each server
connection, which may 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.
Note: If the Client daemon is running in an environment where it survives
user logoff, the default userid and password values entered by the
currently logged on user are retained even when that user logs off, and
are subsequently reused as required.
An application may provide a userid and password on an ECI request and
these values will override any default values set for the server connection as
follows.
v C programs:
Set eci_userid and eci_password or eci_userid2 and eci_password2 in the
ECI parameter block.
v C++ programs:
Set the userid and password parameters when constructing a server
connection object - CclConn.
v Java client programs:
Set the userid and password parameters when constructing an ECIRequest
object.
EPI terminal security
The Client daemon also maintains a userid and password per installed
terminal. These values will override any default values set for the server
connection. They can be set by one of the following methods:
v C programs:
118 CICS Transaction Gateway: UNIX Administration

Client Security
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 programs:
– 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.
– EPI Beans
Set the Userid and Password properties on the extended terminal
properties panel or programmatically by creating an EPI Terminal bean,
get the terminal object it holds using getTerminal() and then use
setUserid and setPassword.
v Terminal Servlet
Set pool@userid and pool@password. These settings apply to all terminals
in the pool.
Terminal security cannot be set when using the CICS CCF Connectors.
Terminal security would normally only be required if using signon incapable
terminals.
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 23, 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
SNA or TCP62. An ESM, such as resource access control facility (RACF ® ), must
also be available to the CICS server. ESI calls can be included within your ECI
Chapter 7. Client Security 119

Client Security
or EPI application. Only CICS servers returned by the CICS_EciListSystems
and CICS_EpiListSystems functions are acceptable.
Signon capable and signon incapable terminals
Signon capable terminals allow signon transactions, either CICS-supplied
(CESN) or user-written, to be run, whereas signon incapable terminals do not
allow these transactions to be run.
If a terminal resource is installed as signon capable, the application or user is
responsible for starting a signon transaction; the userid and password once
entered are embedded in the 3270 data.
v Transactions started before the signon transaction will execute with the
authorities granted to the default userid defined for the server. A check is
also done against the userid associated with the connection to see whether
the Client daemon itself has authority to access the resource.
v Transactions started after the signon transaction will execute with the
authorities granted to the authenticated userid. For transactions attempting
to access resources, security checking is done against the signed-on user’s
userid and the userid associated with the connection. If a server supports
signon timeout and a client terminal is left idle so that the timeout expires,
the user is signed off without notification and the next transaction will run
against the default userid.
If the terminal resource is installed as signon incapable, the userid and
password are authenticated for each transaction started for the terminal
resource.
Prior to Version 3.1.0 of Clients and Gateways, whether a terminal was signon
capable or not was dependant upon the server implementation. Client
terminals installed on distributed CICS servers were signon capable and
terminals installed on mainframe CICS and CICS/400 servers were signon
incapable.
In Version 3.1.0, extended EPI function was introduced to allow the signon
capability of a terminal to be specified by one of the following methods.
v C programs:
Use CICS_EpiAddExTerminal and set the SignonCapability parameter in
the CICS_EpiAttributes_t structure.
v C++ programs:
Set the signon capability parameter when constructing a CclTerminal class
object.
v Java client programs:
– EPI Request Classes
120 CICS Transaction Gateway: UNIX Administration

Set the signon 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 signon capability for the terminal and changes the terminal
type to extended. When you connect, you connect an extended terminal
with that signon capability. If you setSignonCapability while a terminal
is connected then it get’s saved away, it does not alter the connected
setting.
– EPI Beans
Set the SignonCapability property on the extended terminal properties
panel, or programmatically by creating an EPI Terminal bean, get the
terminal object it holds using getTerminal() and then use
setSignonCapability.
v Terminal Servlet
Assign the appropriate Signon capability string to the Servlet Property
pool@signonCapability. These settings apply to all terminals in the pool.
The signon 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 signon capability parameter in the terminal install (CTIN) response.
The signon capability of a terminal cannot be specified when using the CICS
CCF Connectors. If you are using this interface, the EPI functionality available
is unchanged from Version 3.0.x, that is, you cannot specify a userid and
password per terminal, or specify the signon capability.
To use any of the extended EPI functionality, you must ensure that you have
applied the relevant server APAR; see “CICS server PTF requirements” on
page 26.
Refer to CICS Transaction Gateway Programming Guide for further information.
Mainframe CICS servers
These servers support both signon capable and incapable terminals, provided
that they are at the prerequisite maintenance level; see “CICS server PTF
requirements” on page 26. A terminal install request that does not specify any
signon capability, for example from CICS_EpiAddTerminal, will result in a
signon incapable terminal being installed.
For signon capable terminals:
Client Security
Chapter 7. Client Security 121

Client Security
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 signon transaction are flowed to
the server as part of the 3270 datastream and they will therefore appear in a
client trace.
It is recommended that you 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 may fail with an EPI_ERR_SECURITY return code.
v Before the user has signed on, transactions will run under the default
userid for the CICS server. After signon, transactions will run under the
signed-on userid.
For signon incapable terminals without terminal security:
v Use the CICS_EpiAddTerminal call
v A connection userid and password will be required regardless of the setting
of the UseDfltUser in the CICS connection definition on the server.
v Transactions will run under the userid specified in the corresponding FMH
attach request.
For signon 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.
If you wish to use one of the APIs that does not support the new EPI
functionality, then you can use CRTE through a middle tier system to get
signon capable terminal-like functionality.
122 CICS Transaction Gateway: UNIX Administration

Client Security
TXSeries and CICS OS/2 servers
These servers do not support the signon capability parameter in a terminal
install (CTIN) request but will tolerate it if the required APAR is applied; see
“CICS server PTF requirements” on page 26. A terminal install request will
always result in a signon capable terminal being installed, regardless of the
signon capability requested.
CICS/400 servers
These servers do not support the signon capability parameter in a terminal
install (CTIN) request . A terminal install request will result in a signon
incapable terminal being installed, regardless of the signon capability
requested.
Chapter 7. Client Security 123

124 CICS Transaction Gateway: UNIX Administration

Chapter 8. Performance
This chapter helps you to:
v understand the factors that affect CICS Transaction Gateway performance
v achieve the best performance from your system
“Assessing system performance” Read this for an overview of the things to
consider when assessing the performance
of your system.
“CICS Transaction Gateway
configuration” on page 126
Read this for information on CICS
Transaction Gateway configuration
parameters which affect performance.
“Java considerations” on page 128 Read this for information on Java factors
which affect performance.
“Other system factors” on page 128 Read this for information on other system
factors which affect performance.
“Tracing” on page 129 Read this for information on using tracing
to measure performance.
“Performance monitoring tools” on
page 130
Read this for information on performance
monitoring tools.
Assessing system performance
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 WebServer or Web 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.
© Copyright IBM Corp. 1996, 2002 125

CICS Transaction Gateway configuration
CICS Transaction Gateway configuration
IBM has chosen default values for configuration and tuning to give a
compromise between:
v limiting the system resources used by CICS Transaction Gateway after it
has started
v giving 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
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.
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.
If the number of threads needed by applications exceeds the value
specified for Maximum number of Connection Manager threads,
each new request that requires a Connection Manager thread must
wait until a thread becomes available. If the waiting time exceeds the
value specified in the Connection timeout parameter, CICS
Transaction Gateway refuses the connection.
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
126 CICS Transaction Gateway: UNIX Administration

CICS Transaction Gateway configuration
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
v If the value is too low, CICS Transaction Gateway uses resources to
search for available Worker threads.
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 number of transactions per second passing through CICS
Transaction Gateway
v average transaction response time through CICS Transaction
Gateway in seconds
Communication protocols
Your choice of protocol depends on the nature of your client
applications. However, CICS Transaction Gateway does considerably
more processing to handle the HTTP and HTTPS protocols than it
does to handle the TCP and SSL protocols. In addition, when using
HTTP or HTTPS, CICS Transaction Gateway creates a new TCP/IP
connection with each client request. For better performance, use TCP
or SSL in preference to HTTP or HTTPS where possible.
Display TCP/IP hostnames
Selecting this option might cause severe performance reduction on
some systems. See “Display TCP/IP hostnames” on page 55.
Timeout values
It is unlikely that you can improve performance by changing the
default timeout values. However, you may need to change them for
particular applications. Refer to “Configuring CICS Transaction
Gateway settings” on page 53 for more information on these and all
other configuration parameters.
Connection logging
The gateway configuration setting, Log 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 client
connections and disconnections” on page 56.
Chapter 8. Performance 127

Java considerations
Java considerations
Other system factors
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; see
also “java.lang.OutOfMemory exception” on page 193. 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 is enabled by default in JDK 1.3.1. Performance
immediately after a CICS Transaction Gateway has started might be
relatively slow because of JIT overheads. The JIT threshold is 2000 on
JDK 1.3.1 compared with 500 on JDK 1.1.8; that is, each method has to
run 2000 times before it is ’JITed‘. 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 may be small , and the amount of data expected from CICS in
return may 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.
128 CICS Transaction Gateway: UNIX Administration

Tracing
Other system factors
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 Do not use the deprecated setCommareaInboundLength method
because it prevents automatic commarea null stripping.
CICS server transactions
The design of your CICS server transactions affects the performance of
your system. The response time through 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, 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 may 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 may 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.
IBM does not recommend the use of the full CICS Transaction Gateway trace
to monitor performance in a production environment. This is because the
trace itself significantly decreases performance.
Chapter 8. Performance 129

Tracing
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 client application, and also
through CICS and WebSphere.
Performance monitoring tools
The following performance monitoring tools are available on the AIX
operating system. Similar tools are available on other UNIX 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.
IBM Performance Toolbox
Provides some useful performance tools that are integrated into a
graphical user interface. Versions 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.
130 CICS Transaction Gateway: UNIX Administration

Chapter 9. Operating the Gateway
This chapter describes how to operate the Gateway daemon of CICS
Transaction Gateway. It consists of the following:
“Before you start” Read this for information on the
privileges that a user needs to operate
CICS Transaction Gateway.
“Starting the Gateway” on page 132 Read this for information on starting
CICS Transaction Gateway.
“Stopping the Gateway” on page 134 Read this for information on stopping
CICS Transaction Gateway.
“Administering your system” on page 135 Read this for information on setting the
Gateway and JNI traces, and querying
trace settings.
Before you start
To operate CICS Transaction Gateway, you must log in either as root, or as a
user with the following privileges:
v network access through TCP/IP
v read access to file /var/cicscli/shared
v read/write access to directory /var/cicscli
v read access to file CTG.INI
v read access to the directory in which you installed CICS Transaction
Gateway
See also:
v “Security considerations for trace and log files” on page 142, for information
on user access to trace files
v “TCP62 port” on page 76, for information on using TCP62 if you do not log
in as root
© Copyright IBM Corp. 1996, 2002 131

|
Starting the Gateway
You start the Gateway at the operating system command prompt of the
computer on which you have installed it.
First, set your working directory to the /bin subdirectory.
You can start the CICS Transaction Gateway in two ways:
v “Starting the Gateway with preset options”
v “Starting the Gateway with user-specified options”.
Starting the Gateway with preset options
To start the Gateway with predefined options: Type ctgstart at the command
prompt and press Enter.
When you start the Gateway like this the values you configured using the
configuration tool are used. (see “Using the configuration tool” on
page 49).The gateway will not start without a valid INI file.
A Gateway console session starts, and the following messages are displayed
showing the values being used for TCP/IP:
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345
Starting the Gateway with user-specified options
The user-definable options on the start command are:
-port=port_number
-initconnect=number
-maxconnect=number
-initworker=number
-maxworker=number
-trace
-noinput
-tfile=pathname
-x
-tfilesize=number
-truncationsize=number
-dnsnames
-dumpoffset=number
-stack
-jargument to pass to the JVM
where:
-port
Specifies the TCP/IP port number which the gateway will listen on.
-initconnect
Specifies an initial number of ConnectionManager threads.
132 CICS Transaction Gateway: UNIX Administration

-maxconnect
Specifies a maximum number of ConnectionManager threads. If you set
this value to -1, no limits are applied to the number of
ConnectionManager threads.
-initworker
Specifies an initial number of Worker threads.
-maxworker
Specifies a maximum number of Worker threads. If you set this value to
-1, no limits are applied to the number of ConnectionManager threads.
-trace
Enables standard tracing (see “Tracing” on page 185). 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 codepage, is shown at the top of
the trace output.
If you used the configuration tool to configure CICS Transaction Gateway,
the default destination for the trace output is file CTG.TRC in the
/bin subdirectory. Otherwise, trace output is written to
stderr.
-noinput
Disables the reading of input from the console.
-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 185). 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 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, then no data blocks are shown in the trace.
Chapter 9. Operating the Gateway 133

|
|
|
-dnsnames
Enables the display of symbolic TCP/IP hostnames in messages. See
“Display TCP/IP hostnames” on page 55 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 185). Java
exceptions are traced, including those which are expected during normal
operation of the Gateway. No other trace output is created. See the -trace
and -tfile options for information on the destination for trace output.
-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 switch.
To override the startup defaults type ctgstart at the command prompt,
followed by the start-up options you require, and press Enter. Options
specified on the command line override those specified using the configuration
tool.
A Gateway console session starts, and the following messages are displayed
showing the values being used for TCP/IP:
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,
CCL6502I: Initial Workers = 1, Maximum Workers = 100, tcp: Port = 2345
To get help on the startup options, enter:
ctgstart -?
Stopping the Gateway
To stop the Gateway:
v If you did not start the Gateway with the -noinput option, you can stop it
by typing the correct character and pressing the Enter key in the Gateway
console session. The allowable characters may be localized for your country;
the default characters allowed are the Q or - characters.
You can determine which characters will stop the Gateway by simply
pressing the Enter key in the Gateway console session. A message like the
following is displayed:
CCL6508I: Type Q or - to stop the CICS Transaction Gateway.
v If you used the -noinput option, you must stop the Gateway process using
some other method, for example:
– Use the kill command
134 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Administering your system
If you enabled the TCPAdmin protocol (see “TCPAdmin protocol settings” on
page 64), you can perform the following administrative functions without
having to restart the CICS Transaction Gateway:
v Set the Gateway trace
v Set JNI trace
v Query the current trace settings
You execute the Java archive ctgadmin.jar from a command prompt to set
trace or to query trace settings. You can administer the CICS Transaction
Gateway remotely from a workstation that has this JAR file and the supported
level of Java; you do not need to install the CICS Transaction Gateway on the
workstation. See “TCPAdmin protocol settings” on page 64 for details of how
to define which hosts have permission to administer your CICS Transaction
Gateway.
The following sections describe the commands. Parameters are not case
sensitive; those in brackets are optional.
Warning: Do not specify a CICS Transaction Gateway earlier than version 5.0.
Earlier versions cause the administration program to lock. If this
happens, terminate the process, for example by pressing Ctrl+C.
Setting the Gateway trace
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address -a=setgwtrace [-tfile=path]
[-tfilesize=number] [-tlevel=number]
[[-truncationsize=number][-dumpoffset=number]|-fulldatadump]
See “Parameters” on page 136 for an explanation of parameters.
Setting the JNI trace
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address
-a=setjnitrace -tfile=path [-tlevel=number]
See “Parameters” on page 136 for an explanation of parameters.
Querying trace settings
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address -a=qtrace
Administering your system
See “Parameters” on page 136 for an explanation of parameters.
Chapter 9. Operating the Gateway 135

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Administering your system
Parameters
ctg Mandatory. Specifies the Gateway which is to be
administered. You can specify either a hostname, for example
tcp://myserver:2810, or an IP address, for example
tcp://127.0.0.1:2810. In these examples, 2810 is the port you
specified for TCPAdmin; see “TCPAdmin protocol settings” on
page 64.
Warning: Do not specify a CICS Transaction Gateway earlier
than version 5.0. Earlier versions cause the
administration program to lock. If this happens,
terminate the process, for example by pressing
Ctrl+C.
a Mandatory. Defines the action to take. Permitted values are:
v setgwtrace to control Gateway tracing
v setjnitrace to control JNI tracing
v qtrace to determine what trace settings are active
tfile Specifies the output file for Gateway or JNI tracing, for
example ./tracefile.trc. Do not specify the same file for
Gateway and JNI trace output.
Gateway tracing
If you do not specify a value for this tag, trace output is
sent to the console.
JNI tracing
You must specify a value for this tag. If you do not, an
error is displayed.
tlevel Specifies the trace level. Permitted values are:
Gateway tracing:
0 Off. No trace information is output.
1 Exception tracing. Only exceptions are traced.
Equivalent to ctgstart -stack; see “Starting the
Gateway with user-specified options” on page 132.
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).
JNI tracing:
136 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Administering your system
0 Off. No trace information is output.
1 On.
tfilesize Specifies the maximum size, in kilobytes, of the trace output
file, for example 50000.
dumpoffset 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. You
cannot use this together with the fulldatadump parameter.
truncationsize 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 parameter.
fulldatadump Sets the dumpoffset to 0 and ignores any value specified in
truncationsize.
Chapter 9. Operating the Gateway 137

Administering your system
138 CICS Transaction Gateway: UNIX Administration

Chapter 10. Operating the Client daemon
This chapter describes how to operate the Client daemon. It consists of the
following:
“The cicscli command” Read this for an introduction to the Client
daemon command.
“The cicscli command” Read this for information on using the
cicscli command to control the Client
daemon.
“cicscli command reference” on page 145 Read this for a detailed reference to the
cicscli command.
The cicscli command
The cicscli command is used to start and stop 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
use the cicscli command to start the Client daemon explicitly.
You must explicitly terminate any server connections initiated by ECI calls. To
do this, use the cicscli -x=servername or cicscli -i=servername command. See
“cicscli command reference” on page 145.
The cicscli command
The following table shows the functions that you can perform with the cicscli
command, and the parameters associated with each function:
Function Parameters
Start the Client daemon, and start communication with CICS
servers
-s
Stop the Client daemon -i and -x
Restart the Client daemon -j and -y
Start client tracing -d
Stop client tracing -o
Specify the client components to be traced -m
© Copyright IBM Corp. 1996, 2002 139

The cicscli command
Function Parameters
Set up security -c, -u, and -p
List connected CICS servers -l
Enable the display of console messages -e
Disable the display of console messages -n
Wait for confirmation before completion -w
Display information about the version and build level of the Client
daemon
-v
The following sections provide examples of using the cicscli command. Full
details of the command syntax are in “cicscli command reference” on
page 145.
Note: With the cicscli command, you can enter parameters preceded either by
the dash (-) or by the forward slash (/) character.
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.
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 the CICS connection definition, you
must stop and restart the connection.
Stopping the Client daemon in a controlled manner
To stop the Client daemon for all connected servers, after all outstanding units
of work have completed, enter:
cicscli -x
To terminate the session with a particular server, enter:
cicscli -x=servername
140 CICS Transaction Gateway: UNIX Administration

where servername is the name of a CICS server. This stops only the session
with the named server; it does not stop the Client daemon or connections to
other servers.
Stopping the Client daemon immediately
To stop the Client daemon for all connected servers, without completing
outstanding units of work, enter:
cicscli -i
To terminate 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 stop the Client daemon or connections to
other servers.
Note:
If the Client daemon does not stop completely, this may 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.
The cicscli command
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 in a controlled manner
To stop 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.
Restarting the Client daemon immediately
To stop 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.
Chapter 10. Operating the Client daemon 141

The cicscli command
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
parameters together.
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.
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 145.
Stopping client tracing
To stop tracing the Client daemon, enter:
cicscli -o
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, inthe
/var/cicscli subdirectory. You can specify names for these files using the
configuration tool.
The trace file
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, if a user has write access
to the /var/cicscli subdirectory, they can delete CICSCLI.BIN regardless of
the file permissions.
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.
142 CICS Transaction Gateway: UNIX Administration

The Client daemon prevents you from starting tracing if an unauthorized user
has deleted and recreated CICSCLI.BIN.
The 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:
chmod 0700 /var/cicscli
Setting up security
You can use the following commands after first starting the Client daemon.
To set a userid to use when accessing server servername, enter:
cicscli -c=servername -u=userid
where userid is the userid and servername is the servername. (You are
prompted for the password.)
To set a password to use when accessing server servername, enter:
cicscli -c=servername -p=password
where password is the password and servername is the name of the server.
You can enter the -u and -p parameters together.
The cicscli command
You can also specify the security parameters when you start the Client
daemon:
cicscli -s=servername -u=userid -p=password
Version information
To display information about the version and build level of your Client
daemon, enter the command
cicscli -v
The Client daemon displays information similar to Figure 20 on page 144:
Chapter 10. Operating the Client daemon 143

The cicscli command
CCL8001I CICSCLI - CICS Client Control Program
CCL0002I (C) Copyright IBM Corporation 1994, 2002. All rights reserved.
CCL8029I CICS Client for Windows Version 5.0 Service Level 00
CCL8074I Build Level ’c000-20020510a’
CCL8025I The CICS Client has not been started
CCL8023I CICSCLI performed no action
Figure 20. Version and build level information for the Client daemon
Listing the connected servers
To list all the servers being used by the Client daemon, and their status, enter:
cicscli -l
The cicscli control program displays information similar to Figure 21:
CCL8001I CICSCLI - CICS Client Control Program
CCL0002I (C) Copyright IBM Corporation 1994,2002. All rights reserved.
CCL8041I The CICS client is using the following servers:
CCL8042I Server ’CICSAIX’ (using ’TCP/IP’ to ’CICSAIX’) is available
Figure 21. Example list of CICS servers
Disabling the display of messages
To disable the display of all messages output with the command, enter, for
example:
cicscli -s -q
Enabling and disabling the display of console messages
By default, the Client daemon sends error messages to the system console,
/dev/console, and also 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.
To disable the display of console messages, enter:
cicscli -n
To enable the display of console messages again, enter:
cicscli -e
You can specify the -n parameter together with the -s parameter.
The display of console messages is enabled by default.
144 CICS Transaction Gateway: UNIX Administration

Displaying the command parameters
To display the parameters of the cicscli command, enter:
cicscli -?
The cicscli command and applications
You can call cicscli from within applications, if this is supported by the
programming language. You can therefore enter cicscli at the command line,
then run an application to call cicscli with additional parameters.
cicscli command reference
All client control commands have options identified by a leading dash (-).
Instead of dash signs you can use a forward slash (/) for all parameters.
However for the ? parameter 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.
For an explanation of syntax diagrams, see “Conventions and terminology
used in this book” on page viii.
cicscli Command Syntax
►► cicscli -s
-s=servername -d -m -n
-d=nnn -m=components
-o
-d
-d=nnn
-m
-m=components
-x
-x=servername
-i
-i=servername
-l
-j
-y
-c=servername
-u=userid -p=password
-u -p
-e
-n
-v
-?
The cicscli command
The options are:
-c=servername Identifies the name of the server to which security information
in the form of a userid and password is to be associated.
-q
-w
Chapter 10. Operating the Client daemon 145
►◄

The cicscli command
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
userid and password, unless these have already been
provided via cicscli (see the descriptions of 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.
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 197.
-e Enables the display of Client daemon error and security
messages on the console.
-i Stops the Client daemon immediately. The options
-i=servername and -i operate as for -x=servername and -x
respectively but the Client daemon does not wait for
outstanding units of work to complete. Stopping the Client
daemon in this way may result in a loss of data at connected
servers.
-j Stops 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.
Using -y is the preferred way of restarting the Client daemon.
-l Causes a list of all connected servers to be displayed. 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.
146 CICS Transaction Gateway: UNIX Administration

The cicscli command
-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:
ALL All components
API.1 The client API layer (level 1). This gives basic
API tracing.
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 Interprocess communication
For guidance on when to use the tracing options, see
“Choosing which components to trace” on page 196.
The -m parameter 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 you must specify
the -s parameter before you use -m.
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.
Chapter 10. Operating the Client daemon 147

The cicscli command
You can also specify settings for trace components using the
configuration tool (see “Trace settings” on page 78 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, 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.
For the API and DRV components, you can specify the level
of information to trace. For example components API or API.1
specify that basic API-related information is traced before and
after ECI and EPI calls. Component API.2 specifies that
additional API trace entries are produced in addition to those
of level 1.
Note that the cicscli -d=nnn command is used to set the
maximum size of the data areas to be traced. The trace data
may be truncated if you set nnn lower than the size of data
expected.
-n Disables the display of Client daemon error and security
messages on the console
Any messages that would have been logged are still logged.
-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 parameter. This password is used if
the server requires a password (and userid) before running
transactions on the client’s behalf.
For ECI applications, any userid and password specified in
the ECI parameter block overrides values set via 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 output with 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 exist in the configuration file.
148 CICS Transaction Gateway: UNIX Administration

The cicscli command
-u=userid Sets the current userid to be used when accessing the server
specified by the -c parameter. This userid is used if the server
requires a userid (and password) before running transactions
for the Client daemon.
If you do not provide the -p parameter, you are prompted for
the password.
For ECI applications, any userid and password specified in
the ECI parameter block overrides values set via the cicscli
command.
Specifying -u or -u= (that is, no userid is specified) resets the
associated userid to a null value.
-v Displays information about the version and build level of the
Client daemon.
-x Stops the Client daemon in a controlled manner. If
-x=servername is specified, then when all outstanding units of
work on the specified server have completed, the connection
to the server is terminated. If other server connections are
active, these remain unchanged.
If -x is specified without a servername, 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 in a controlled manner.
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 re-established when the Client daemon is
restarted.
Using -y is the preferred way of restarting the Client daemon.
-? Causes the command syntax to be displayed.
Note: The -f parameter is no longer supported. See “Using the configuration
tool” on page 49 for information on how to specify a configuration file.
Chapter 10. Operating the Client daemon 149

The cicscli command
150 CICS Transaction Gateway: UNIX Administration

Chapter 11. Terminal Emulation
This chapter describes how to use the cicsterm and cicsprnt programs. It
consists of the following:
“Summary of Terminal Emulation
commands”
“cicsterm command reference” on
page 154
Read this for a summary of the
commands explained in this chapter.
Read this for a detailed reference to the
cicsterm command.
“The cicsprnt command” on page 157 Read this for information on using the
cicsprnt command to control 3270 printer
terminal emulation.
“cicsprnt command reference” on
page 158
Summary of Terminal Emulation commands
Read this for a detailed reference to the
cicsprnt 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
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 on UNIX operating systems.
Note: Some uses of servers and protocols require a model terminal definition
for the emulator that explicitly specifies that the Client daemon wants
to display DBCS.
© Copyright IBM Corp. 1996, 2002 151

The cicsterm command
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 signon incapable -a
Determine the print file processing -p
Specify a file to which print files are appended -f
cicsterm command once with all the parameters you require.
The following is an example of a cicsterm command:
cicsterm -s=CICSOS2 -t=CESN -k=mykeys.ini -c=mycols.ini
-n=cicsv123 -f=clprint.txt -q
In this example:
-s=CICSOS2 Specifies that a 3270 terminal emulator is started for the server
CICSOS2.
-t=CESN Specifies that the initial transaction is CESN.
-k=mykeys.ini Specifies that the keyboard mapping file is named as
mykeys.ini.
-c=mycols.ini Specifies that the color mapping file is named as mycols.ini.
-n=cicsv123 Specifies that the 3270 terminal emulator characteristics are
defined by the terminal definition cicsv123.
-f=clprint.txt Specifies that the print file will be appended to the file
clprint.txt.
-q Specifies that the display of messages output by the command
is disabled.
All parameters of cicsterm are optional. That is, you can enter the cicsterm
command without any parameters, and defaults are taken from the
configuration file. Full details of the parameters are given in “cicsterm
command reference” on page 154.
152 CICS Transaction Gateway: UNIX Administration

Stopping a terminal emulator
To stop a terminal emulator, enter, from an empty terminal screen, the string
specified by the Terminal exit configuration setting, and press Enter. The
default string is EXIT
cicsterm and user exits
You can use cicsterm to drive EPI user exits.
The cicsterm command
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 straight away 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.
Using X-Windows Clients
There are some known problems with certain X-Windows clients (such as
Exceed). These include corruption of the text on the title bar of the window
that you are trying to display, This might happen, for example, with the
Configuration Tool. In some cases the title bar might be missing. The
problems relate to the X-Windows client used and not to the Client daemon.
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 your settings in Exceed’s Xconfig as follows:
a. Launch Xconfig
b. Select ’screen definition’
c. Alter 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.
Chapter 11. Terminal Emulation 153

The cicsterm command
Using cicsterm with an XTERM window
When cicsterm runs in an XTERM window it may not recognise all function
keys. This is because of the terminal type.
There are two ways to solve this problem::
1. Run cicsterm in a non XTERM window
2. Set the TERM environment variable for the session to a different terminal
type, such as vt100 (by default, this environment variable is often set to
xtterm).
cicsterm command reference
For an explanation of syntax diagrams, see “Conventions and terminology
used in this book” on page viii.
You can enter parameters preceded by the dash (-) or by the forward slash (/)
character. However for the ? parameter you must use a dash.
cicsterm Command Syntax
►► cicsterm
►
►
-s = servername -t=initialtransid
-s -t
-r=servername
-r
-k=keyfile -c=colorfile -m=modelname -a
-c -m
-n=netname -p=printcmd -q -?
-f=printfile -w
The options are:
-a Specifies that the terminal emulator is not signon capable. By default,
cicsterm creates terminal emulators that are signon capable.
For more information on signon 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 90
for more details. If you omit this parameter, the environment variable
CICSCOL is assumed to identify the color mapping file. If CICSCOL is
not defined, a filename of CICSCOL.INI in the /bin
subdirectory is assumed.
154 CICS Transaction Gateway: UNIX Administration
►
►
►◄

The cicsterm command
If the parameter is specified as -c=, that is, the color mapping filename
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 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 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 88 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 filename 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. For example, on CICS for OS/2 it
references a termid defined in the CICS tables, but on TXSeries for
AIX it is a netname.
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, then
Chapter 11. Terminal Emulation 155

The cicsterm command
the command must be enclosed 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 filename
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 terminal emulator 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 terminal. 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.
This option is case sensitive.
156 CICS Transaction Gateway: UNIX Administration
Note: Be careful that transactions that you specify either here or in
the configuration file do not require terminal input to complete.

-? Causes the parameter syntax to be listed; any other options specified
are ignored.
The cicsprnt command
The cicsprnt command controls 3270 printer terminal emulation.
An application running on a server can direct output to a printer in one of
two ways:
1. An application running from a terminal can initiate printing by sending a
map or data with the PRINT indicator set
2. 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.
Note: 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.
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 -f
Wait for confirmation before completing -q
Inhibit all ouput messages -q
Issue one print job per transaction -j
You issue the cicsprnt command once with all the parameters you require.
The following is an example of a cicsprnt command:
cicsprnt -s=CICSOS2 -n=P123 -t=XPRT -f=clprint.txt -q
In this example:
The cicsterm command
Chapter 11. Terminal Emulation 157

The cicsprnt command
-s=CICSOS2 Specifies that a 3270 print terminal emulator is started for the
server CICSOS2.
-n=P123 Specifies that the 3270 print terminal emulator characteristics
are defined by the terminal definition P123 (in the terminal
control table for CICS for OS/2 in this case.)
-t=XPRT Specifies that the initial transaction is XPRT.
-f=clprint.txt Specifies that the print file to which print requests are
appended is clprint.txt.
-q Specifies that the display of messages output by the command
is disabled.
All parameters of cicsprnt are optional, except that you must specify either
-n=netname or -m=modelname. That is, you can enter the cicsprnt command
with just the -n or the -m parameter, or both, and defaults for other
parameters are taken from the configuration file. Full details of the parameters
are given in “cicsprnt command reference”.
If the system upon which the Client daemon is running 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.
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 the commands:
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 153.
cicsprnt command reference
For an explanation of syntax diagrams, see “Conventions and terminology
used in this book” on page viii.
You can enter parameters preceded by the dash (-) or by the forward slash (/)
character. However for the ? parameter you must use a dash.
158 CICS Transaction Gateway: UNIX Administration

cicsprnt Command Syntax
►► cicsprnt
-s=servername -t=initialtransid -j
-s -t
-r=servername
-r
► -m=modelname
-n=netname -p=printcmd -q -?
-f=printfile -w
The options are:
-f=printfile
Specifies the name of a file to which the output of print requests is
appended. 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 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.
-j
The cicsprnt command
►
►◄
Chapter 11. Terminal Emulation 159

The cicsprnt command
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, then 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 filename
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.
160 CICS Transaction Gateway: UNIX Administration

The cicsprnt command
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.
-? Causes the parameter syntax to be listed; any other options specified
are ignored.
Chapter 11. Terminal Emulation 161

The cicsprnt command
162 CICS Transaction Gateway: UNIX Administration

Chapter 12. The Terminal Servlet program
This chapter describes how to use the Terminal Servlet to access CICS 3270
applications using a Web browser.
v “What is the CICS Transaction Gateway Terminal Servlet?” tells you what a
servlet is, and in particular what the CICS Transaction Gateway Terminal
Servlet does.
v “Installing and configuring the Terminal Servlet” on page 165 discusses how
you install and configure the Terminal Servlet.
v “Using the Terminal Servlet” on page 171 describes what you can do with
the Terminal Servlet, and how to invoke it from your Web pages.
v “Properties and parameters reference” on page 176 provides a complete
reference to the servlet properties you can specify for the Terminal Servlet.
v “Migrating from the CICS Internet Gateway on AIX” on page 220 describes
what you need to do to migrate from AIX running the CICS Internet
Gateway to using the Terminal Servlet.
v “CICS Transaction Server for z/OS Web Interface” on page 182 describes
how HTML templates generated for use by the CICS Web Interface can be
used by the Terminal Servlet.
It is advisable to read through all of this chapter before configuring and using
the Terminal Servlet.
What is the CICS Transaction Gateway Terminal Servlet?
Servlets are Java programs that run on a Web server machine, inside a
Java-enabled Web server or servlet engine, for example, WebSphere
Application Server (see Figure 22 on page 165). Java servlets have become
popular as alternatives to Common Gateway Interface (CGI) programs—the
Terminal Servlet is a replacement for the CICS Internet Gateway shipped with
IBM CICS Clients Version 2, which was a CGI program.
A servlet can be loaded automatically when the Web server is started, or
loaded when the first client request for the services of the servlet is made.
Unlike CGI programs, servlets are persistent, that is, once they are loaded
they stay running, waiting for additional client requests.
Being Java programs, servlets are portable across operating systems. And,
because the servlet interface is a standard, they can be used with different
Web servers on different platforms.
© Copyright IBM Corp. 1996, 2002 163

CICS Transaction Gateway Terminal Servlet
The Terminal Servlet allows you to access CICS 3270 applications using a Web
browser. You create Web pages that invoke the Terminal Servlet to start a
CICS transaction, display screen information sent from a CICS server, and
send screens back to CICS.
The Terminal Servlet can:
v Behave like a simple terminal emulator.
The CICS screen is displayed in the browser as part of an HTML form.
When you press one of the buttons in the form, the form is submitted and
data is sent to CICS.
v Substitute data from a CICS screen into HTML template files.
An HTML template file is used to determine how CICS data appears in the
browser. The Terminal Servlet replaces variables in the HTML template file
with CICS screen information, and the resulting output is sent to the
browser. For more information, see “Using variable substitution” on
page 174.
v Using server-side includes, incorporate variable information in a Web
page, or drive a terminal emulator without user interaction.
Server-side includes are statements in an HTML file (.shtml) that are
processed by the Web server before the Web page is returned to the
browser. For example, you can use a server-side include to invoke the
Terminal Servlet to display the value of fields in a CICS screen. For more
information, see “Invoking the servlet with a server-side include” on
page 173.
v Map CICS screens to Web pages.
Using the page mapping properties of the Terminal Servlet, you can
associate particular Web pages with particular CICS screens. For example,
you can specify the Web page to be displayed when the terminal is idle,
and no transaction is running. For more information, see “Page mapping
properties” on page 179.
Like EPI programming, the Terminal Servlet allows you to create new front
ends to existing CICS transactions. However, it also allows you to exploit the
power, flexibility, and platform-independence of Java programming.
Note: The Terminal Servlet does not support DBCS fields in 3270 data
streams.
164 CICS Transaction Gateway: UNIX Administration

Workstation
Java-enabled browser
HTTP
Gateway server
Web server / servlet engine
Servlet
Gateway daemon
Client daemon
TCP62
CICS Transaction Server for OS/390
CICS server
Installing and configuring the Terminal Servlet
CICS Transaction Gateway Terminal Servlet
Figure 22. CICS Transaction Gateway using Terminal Servlet invoked by URL
This section discusses how to install the Terminal Servlet on the Web server
machine, and set the initialization parameters of the Terminal Servlet.
The procedure for installing and configuring the Terminal Servlet will vary
according to the Web server. However, you will need to do at least the
following:
v Configure the Web server’s CLASSPATH and PATH settings
v Add the Terminal Servlet to the Web server’s configuration
v Configure the servlet initialization parameters
v Consider other configuration options, such as security, logging, and
whether the Web server can process server-side includes.
Chapter 12. The Terminal Servlet program 165

CICS Transaction Gateway Terminal Servlet
Examples of installing and configuring the Terminal Servlet on a particular
Web server are available in the sample configuration documents. See “Sample
configuration documents” on page 238. The principles described should also
apply to other Web servers.
Refer to the documentation for your Web server for information on installing
and configuring servlets.
Configuring the Web server’s CLASSPATH and PATH settings
You must ensure that the two CICS Transaction Gateway jar files,
ctgclient.jar and ctgserver.jar, are in the Web server’s classpath.
If you do not make the correct classpath settings, you may get a message to
the effect that you cannot update the servlet, and that the class
com.ibm.ctg.servlet.TerminalServlet cannot be loaded.
You must also ensure that the /bin subdirectory is in the Web
server’s path.
Adding the Terminal Servlet to the Web server’s configuration
To add the Terminal Servlet to the Web server’s configuration, you must
provide a Servlet Name and associate this servlet instance with the Terminal
Servlet class, which is com.ibm.ctg.servlet.TerminalServlet.
You can configure more than one instance of the Terminal Servlet. Each of
them would have a different Servlet Name, but would refer to the same
Servlet Class. In fact, you must create a different Terminal Servlet instance for
each CICS server that you want to connect to. Each instance of the Terminal
Servlet may use different initialization parameters, and this can be useful
when configuring for different CICS servers.
Configuring the servlet initialization parameters
After adding the Terminal Servlet to the Web server’s configuration, you must
set up the initialization parameters for the Terminal Servlet.
The following sections give some insight into how the Terminal Servlet works,
which will help you in setting appropriate servlet initialization parameters.
The Terminal Servlet now supports signon capable terminals. For information
on the full set of initialization parameters available, including those to provide
this type of terminal, refer to “Properties and parameters reference” on
page 176.
166 CICS Transaction Gateway: UNIX Administration

As a starting point consider setting some of the following parameters:
Table 9. Servlet initialization parameters
Parameter name Notes
servlet@propertyFile The servlet can load configuration information from a
properties file. A sample servlet.properties file is
supplied, in the
/samples/terminalservlet subdirectory.
To use a properties file, set this parameter to the full
path name of the properties file you want the Terminal
Servlet to load. If you specify a properties file then you
may want to use this file for all other servlet
parameters. In this case, servlet@propertyFile is the
only parameter that you need to set.
servlet@extendedLogging The servlet writes logging information, for example,
error messages, to the standard servlet log. Set this
property to true to write more information to the log
file. You may find this helpful when first configuring
the servlet, but it should be turned off once the servlet
is set up correctly.
pool@maxTerminals Set this property to the maximum allowable number of
connections to the CICS server. You should ensure that
the CICS server has sufficient free tasks to handle this
number of concurrent connections. You should also
ensure that the CICS Client Maximum requests
configuration setting is at least as large as this property.
pool@serverName Each instance of the Terminal Servlet can connect to
only one CICS server. This gives you more control of
resource usage and security. Set this property to the
name of the required CICS server, as defined by the
appropriate Server name setting in your configuration.
If this property is not set, the default CICS server is
used.
pool@gatewayUrl Set this property if you want the servlet to connect over
the network to the CICS Transaction Gateway.
Apart from the name of the property file, all the servlet properties can either
be loaded from a properties file or set as servlet initialization parameters.
Initialization parameters override properties file entries.
The servlet property names are not case sensitive.
CICS Transaction Gateway Terminal Servlet
Terminal pooling
The Terminal Servlet uses a pool of terminals, and the servlet configuration
properties allow you to control the behavior of the terminal pool. The default
Chapter 12. The Terminal Servlet program 167

CICS Transaction Gateway Terminal Servlet
behavior is that a new terminal is connected to CICS whenever a user requires
one, up to the pool@maxTerminals limit. When the user has finished with the
terminal, it is disconnected.
If the pool@minTerminals property is set, this number of terminals is
connected to CICS when the servlet starts, and up to that number may be
connected to CICS but not in use at any time. This allows new users to be
allocated a terminal immediately, without waiting for a connection.
Setting the pool@reusingTerminals property allows terminals to be reused,
that is, when a user session ends, the terminal may be allocated to a new user
instead of being disconnected. This property has no effect if
pool@minTerminals is 0. Any transaction running on the terminal is ended
and the screen is cleared, before it is reused. However, if a user has signed on
to CICS (using CESN for example), the terminal will still be signed on when it
is reused. For this reason, do not set this property unless you are sure it is
suitable for your environment.
The pool@idleTimeout property allows terminals that have been allocated to
a user to be released if they have not been used for the specified timeout
period. This property defaults to 0, that is, no timeout.
Using a display request with the values: pool@connectedTerminals,
pool@freeTerminals, and pool@terminalsInUse, you can query the number of
terminals that are connected, free, or in use for a particular instance of the
Terminal Servlet.
Page mappings
Page mappings tell the Terminal Servlet what Web page to display for a
particular CICS screen or terminal state.
The servlet’s choice of which page to display is based on the current page
mapping settings, the current screen handler class, and the state of the
terminal.
The Terminal Servlet first looks at the page mapping properties to see if there
is a specific page set for the current state of the session, as follows:
Session State Page Mapping Property
an error has occurred page@error
the terminal is idle - no transaction is
running
page@idle
the terminal has been disconnected page@disconnected
there is a screen handler for the current Page mapping for the class name of the
screen
screen handler
168 CICS Transaction Gateway: UNIX Administration

If no specific page is found, the page identified by the page mapping property
page@default is used. If this is not set, an error message is displayed instead.
The value of a page mapping property can be set in two ways:
1. A URL, for example:
http://webserver/index.html
2. A template file to be loaded for variable substitution. This must start with
″file://″, for example:
file://d:/pages/template.html
CICS Transaction Gateway Terminal Servlet
If you set the servlet@templateDir property, template filenames can be
specified relative to the template directory.
Example settings for page mapping properties are as follows:
page@error=http://server/errors.html
page@idle=http://server/idle.html
page@disconnected=/ctglab/html/servlet/epissam.html
page@default=file://epissam1.html
To set a page mapping for a particular screen, you must create a Screen
Handler bean that can recognize that screen. Then, you must set the
pool@handlerPath property to ensure that the Screen Handler bean is loaded
by the Terminal Servlet. If, for example, you have created a Screen Handler
bean called MAP1ScreenHandler in a package called testmaps, then the page
mapping property for that screen handler is:
page@testmaps.MAP1ScreenHandler.
The name of the class is case sensitive. As for the standard page mappings,
you set the property to the name of the Web page to display, for example:
page@testmaps.MAP1ScreenHandler=http://server/test.html
A page mapping can also be set in a request parameter to the Terminal
Servlet, in which case it applies only to that request and overrides any page
mappings associated with the instance of the servlet being used. You can
query the current setting of a page mapping with an appropriate request (see
“Displayable properties” on page 181).
Screen Handler beans and terminal disconnection
For a terminal to be disconnected successfully, it must exit from running
transactions. The Terminal Servlet’s default behavior for achieving this is to
send the AID (Attention identifier) PF3 key to CICS. However, if you will be
running transactions for which this will not work, you should create one or
more Screen Handler beans that know how to exit the relevant screens.
Chapter 12. The Terminal Servlet program 169

CICS Transaction Gateway Terminal Servlet
You can generate Screen Handler beans automatically from BMS maps using
the BMS Map Conversion Utility (BMSMapConvert) supplied with the CICS
Transaction Gateway, or you can write your own classes. For information
about Screen handlers and how to create them, see the CICS Transaction
Gateway: Programming Guide book.
To load screen handlers into the servlet, set the pool@handlerPath property.
The handler path can include .jar files, .zip files and directories, although
sub-directories will not be searched. For example, in the servlet properties file
you might add:
pool@handlerPath=d:/handlers/handlers.jar;d:/handlers/test
to load screen handler classes from a .jar file and from a directory. See the
sample properties file for more information on setting this property.
You can also specify a default screen handler (using the property
pool@defaultHandler), which is used to exit from a screen if no other screen
handler recognizes it. The sample default screen handler is
com.ibm.ctg.epi.DefaultScreenHandler, which sends the AID PF3 to CICS.
Any screen handler bean that can be loaded from the classpath or from the
handler path can be used as the default screen handler.
The servlet will not keep trying to exit a running transaction indefinitely. The
property pool@exitRetryLimit controls how many attempts it makes to exit
the transaction. The default value of this property is 10, but you should
ensure it is large enough for your environment. If the servlet finds there is
still a transaction running on the terminal after this many attempts to exit, the
terminal is assumed to be ‘dead’ and it will not be disconnected or allocated
to a user. The only way to discard dead terminals is to unload the servlet,
stop and restart the CICS Transaction Gateway, and load the servlet again.
If you have configured the servlet properly and provided Screen handler
beans, you should not have any dead terminals.
Considering other configuration options
Other configuration options that you should consider are:
v Security
You may need to control access to the Terminal Servlet.
v Logging
The Terminal Servlet writes log information to the standard servlet log. You
can set logging on or off.
v Session tracking
You should configure the Terminal Servlet to use session tracking.
v Server-side includes
170 CICS Transaction Gateway: UNIX Administration

You may wish to configure your Web server to process server-side includes.
Loading the Terminal Servlet
After you have configured the Terminal Servlet and saved the settings, you
must load it. You can choose whether to load it immediately, or each time
your Web server starts up.
Using the Terminal Servlet
If you have not configured the Terminal Servlet properly, error messages are
displayed when the Web server attempts to load the Terminal Servlet. For
more information refer to the Terminal Servlet section in the CICS Transaction
Gateway: Gateway Messages book.
This section describes how to use the Terminal Servlet. It describes the
different ways in which the Terminal Servlet can be invoked, and also how to
develop the Web pages that use the Terminal Servlet.
Sample files are provided in the /samples/terminalservlet
subdirectory. File samples.txt describes the samples.
Connecting to CICS and starting a transaction
An instance of the Terminal Servlet can only connect to one CICS server. For
each CICS server that you want to allow access to, you will have created an
instance of the servlet. You might also have created instances of the servlet
that have different initialization parameters.
To start a transaction on the CICS server, you must invoke the Terminal
Servlet with a suitable request.
Invoking the Terminal Servlet
There are three ways to invoke the Terminal Servlet:
v by URL
v with an HTML form
v with a server-side include.
CICS Transaction Gateway Terminal Servlet
In each case, you need to know the name of the servlet instance that you
want to use, and you pass the servlet one or more request parameters that tell
it what action to take. The parameter names and values are the same in all
cases, but the way you specify them is different.
To start a transaction on the CICS server, the parameters you must provide
are:
Chapter 12. The Terminal Servlet program 171

Using the Terminal Servlet
Parameter Name Parameter Value
request send
transaction the transaction ID of the transaction you want started.
Note however that ATI transactions cannot be started for the
Terminal Servlet.
The servlet will allocate a terminal to the user, if it is required.
The full set of request parameters are listed in “Request parameters” on
page 180.
Invoking the servlet by URL
To invoke a servlet instance called TerminalServlet, link to the URL:
http://your_webserver/servlet/TerminalServlet
where your_webserver is the hostname of your Web server and /servlet/ is the
location of your servlet engine (or the context for the servlet).
You can encode request parameters in the URL in the form of a query string,
for example:
http://your_webserver/servlet/TerminalServlet?request=send&transaction=CECI
You should use this method of invoking the servlet when you do not need the
user to enter any information.
Invoking the servlet with an HTML form
With this method, you create an HTML form in a Web page. For example:
(Tags to place text entry areas, buttons, and other prompts go here)
is a form that would invoke the servlet called TerminalServlet. The METHOD
can be GET or POST. The various elements of the form have names and
values, and these are sent to the servlet when the form is submitted. If you
know you want to set a particular request parameter, add it as a hidden item
in the form, for example: . Hidden inputs are always sent to the servlet. In general, the
name of a form element is the name of a request parameter, and its value is
the value of the request parameter.
This is the only way to send user-entered information to the servlet.
The supplied sample, epissam3.html, illustrates the HTML form method; see
the samples.txt file on the product CD.
172 CICS Transaction Gateway: UNIX Administration

Invoking the servlet with a server-side include
A server-side include is processed by the Web server before the Web page is
sent to the user. The servlet is invoked, and any output it generates is
included in the Web page in place of the server-side include tags. The user
only sees the servlet output in the Web page.
In the HTML source, a WebSphere server-side include of the servlet looks like
this:
A server-side include can be used to add variable information to a Web page,
or to drive a terminal to perform some action whenever a Web page is
displayed, without any user involvement.
You can add as many server-side includes to a Web page as you wish, but
note:
v Server-side includes in one page may be processed in parallel. You can
therefore not be sure in which order they are performed, although usually
this is the order in which they occur in the source.
v The servlet stores session information that allows it to access the terminal
allocated to a user. If the user session is invoked by a server-side include,
subsequent server-side includes in the same page will not be able to access
the session information. Once the page has been sent to the user, the
session is established, and a page with multiple server-side includes will
work correctly.
The supplied sample
/samples/terminalservlet/epissam2.shtml illustrates the
server-side include method.
What happens next?
When the servlet has been invoked from a form or by linking to a URL, some
output must be sent back to the browser. To decide what should be displayed
to the user, the servlet uses the page mapping properties that you have set up,
see “Page mappings” on page 168.
Displaying screens and fields
There are two ways to include CICS screen information in a Web page:
v server-side includes
v variable substitution.
You can mix the two approaches if you want to.
Using the Terminal Servlet
Chapter 12. The Terminal Servlet program 173

Using the Terminal Servlet
Using server-side includes
Your Web server must be configured to process server-side includes. You
create SHTML pages that contain server-side includes that invoke the servlet.
The output from the servlet is inserted into the page in place of the
server-side include.
For example, to display the screen, as part of an HTML form, using
WebSphere:
or to display the contents of the 22nd field on the screen, using WebSphere:
Using variable substitution
You create HTML template files that the servlet will load. The servlet replaces
variables in the file with CICS screen information, and the resulting output is
sent to the browser. You use page mapping properties to tell the servlet what
template file to load (see “Page mappings” on page 168).
For example, a template file for the CESN signon screen might look like:
CICS Signon
CICS Signon
Userid:
Password:
where the variables are &USERID; and &PASSWORD;. You can identify fields
by number - to use names for fields, as in this example, you must have a
Screen Handler bean which can recognize the screen and set fields by name.
Page mapping property values can be the names of HTML template files or
any URL. So that the servlet knows that a page mapping property identifies
174 CICS Transaction Gateway: UNIX Administration

an HTML template, you should set it to the value file://template_filename, for
example: file://d:/html/templates/test.html.
What can be displayed?
Any piece of information that can be displayed by a server-side include can
also be used for variable substitution, and vice-versa. The variable name used
in a template is the same as the value of the display parameter in the
server-side include.
Generally, you can display:
v The screen, as part of an HTML form
v A field - identified by number, or by name, if you have a Screen Handler
bean for it
v Servlet configuration settings
v The number of terminals that are currently connected, in use, and free.
The full set of properties that can be displayed is listed in “Properties and
parameters reference” on page 176.
Sending the screen back to CICS
To send the screen back to CICS you must invoke the servlet with the request
parameter set to ″send″. You do not need to provide a transaction parameter -
it is ignored if a transaction is already running. To update the screen with
new information before sending it back to CICS, you specify further request
parameters that identify the fields (by name or number) and what they should
be set to.
For example, the following WebSphere server-side include:
sets the fields named USERID and PASSWORD to the values given, and then
send the screen to CICS. In an HTML form, you might use the form element
. When the user
submits the form, the request parameter USERID is set to the value that they
entered.
Setting the AID
The default AID is Enter.
Using the Terminal Servlet
To set the AID from an HTML form, include a Submit button, specified like
this:
Chapter 12. The Terminal Servlet program 175

Using the Terminal Servlet
.
If the user presses the button, the servlet is sent the request parameter
″DFH_PF3″ with the value ″Exit″ (which the servlet ignores). The AID is set to
PF3. In a,WebSphere server-side include, you could set the AID like this:
The full set of request parameters is listed in see “Properties and parameters
reference”.
Disconnecting
When the servlet has allocated a terminal to a user, it is retained until:
v The servlet is invoked with the parameter ″request″ set to ″disconnect″
v The user’s session on the Web server expires
v If the pool@idleTimeout property has been set, the terminal is
automatically disconnected if it is not accessed for the specified period of
time.
v The CICS Client is stopped
v The connection to the CICS server is lost - or the server goes down
v The servlet is unloaded by the Web server.
You should try to explicitly release terminals when they are no longer
required.
Note that when a user has established a session with the servlet and been
allocated a terminal, any instance of the servlet to which the user has access
can continue the session. The same terminal is used until the user disconnects
or the session is ended for some other reason. The page mappings and other
properties used for any particular request are those set for the instance of the
servlet that is processing the request.
Properties that can be set as request parameters, for example, page mappings,
override the settings for the servlet, but usually only apply to the current
request, and do not affect requests by other users or subsequent requests by
the same user.
Properties and parameters reference
This section describes the Terminal Servlet properties
176 CICS Transaction Gateway: UNIX Administration

Properties and parameters reference
Servlet configuration properties
In general, these properties can be specified either in a properties file or as
servlet initialization parameters when you configure the Web server. The
names are not case sensitive. Values given as servlet initialization parameters
override settings loaded from a properties file. Apart from the servlet@debug
and servlet@extendedLogging properties, these settings cannot be changed
while the servlet is running. However, using the request parameter display,
you can query the current settings of a property, see “Displayable properties”
on page 181.
servlet@debug
If set to true, turns tracing on for all instances of the servlet. You can
turn tracing on or off while the servlet is running, and output is
directed to standard output. Note that turning tracing on seriously
impacts performance!
servlet@extendedLogging
If set to true, turns extended logging on. Output is directed to the
servlet log.
servlet@propertyFile
The full path name of a properties file to load. This property can only
usefully be set as a servlet initialization parameter.
servlet@templateDir
The name of a directory from which HTML template files can be
loaded. Setting this property prevents users from viewing files that
are not in the template directory or its subdirectories. If you do not set
this property, the servlet can load any file on the Web server that it
has access to.
pool@defaultHandler
The screen handler to use to exit screens when no specific handler is
found. If you set this to be one of the Screen Handlers loaded from
the Screen Handler path, make sure that the handler path is set before
the default handler.
pool@deviceType
The terminal model definition to use. If this property is not set, the
default is used.
pool@encoding
Allows you to specify the Java Encoding to be used. Refer to
″Appendix A. Java encodings″ in the CICS Transaction Gateway:
Programming Reference book for further details on this.
pool@exitRetryLimit
The number of times that the servlet will try to exit a running
transaction during terminal disconnection. This prevents the servlet
looping, if a screen cannot be exited.
Chapter 12. The Terminal Servlet program 177

Properties and parameters reference
pool@gatewayUrl
The URL of the CICS Transaction Gateway that the servlet should
connect to. The default is to use a local Gateway, that is local://.
pool@handlerPath
The path from which Screen Handler beans are loaded. You can
include directories, .jar files, and .zip files, but subdirectories are not
searched.
pool@idleTimeout
The maximum time in seconds to allow a terminal to be left idle
before it is automatically disconnected. The default value is 0,
meaning no timeout.
pool@installTimeout
The maximum time in seconds to allow a terminal to install before
failing. The valid range is 0 to 3600. The default value is 0, meaning
no timeout
pool@maxTerminals
The maximum number of terminals that can be connected to CICS
concurrently. The default value is 5.
pool@minTerminals
The number of terminals that should be kept connected to CICS when
not in use. The default value is 0.
pool@password
Specifies the password to be associated with a signon incapable
terminal at the time of creation.
pool@readTimeout
The maximum time in seconds to allow for conversational
transactions before timing out.. Valid range is 0 to 3600. A value of 0
meaning no timeout.
pool@reusingTerminals
If set to true, released terminals are kept connected for the next user.
The default behavior is to disconnect terminals when a user session
ends. You must also set pool@minTerminals for this property to have
any effect.
pool@serverName
The name of the CICS server to connect to. If this property is not set,
the default CICS server, as defined in your configuration is used.
pool@signonCapability
Specifies signon capability for extended terminals. Valid entries are
EPI_SIGNON_CAPABLE or EPI_SIGNON_INCAPABLE.
178 CICS Transaction Gateway: UNIX Administration

Properties and parameters reference
pool@pool@userid
Specifies the userid to be associated with a signon incapable terminal
at the time of creation.
screen@coloring
If set to true, colored fields are displayed in the color indicated in the
3270 datastream.
Due to the limitations of HTML, unprotected fields cannot be colored
and always appear as black text on a white background.
If the property is not specified. the Terminal Servlet displays the
screen with black text on a white background.
screen@cursoring
If set to true, JavaScript sets the screen cursor position. The default
setting is false.
screen@NeutralColor
Specifies the HTML color to which the screen handler will translate
the neutral 3270 color.
screen@stripBlanks
If set to true, the Web Browser formats the field text.
screen@stripEmptyRows
If set to true, the screen handler removes screen rows that do not
contain data.
screen@TrimFields
If set to true, the screen handler removes excess white space from the
start and end of any input fields.
Page mapping properties
Page mappings associate Web pages with particular screens or terminal states.
Page mappings can be specified in a properties file, or as servlet initialization
parameters, when you configure the Web server. However, using the request
parameter display, you can query the current settings of a page mapping, see
“Displayable properties” on page 181.
Standard page mapping properties Value
page@disconnected The page to show when the terminal is
disconnected.
page@error The page to show when an error occurs
page@idle The page to show when the terminal is
idle, that is, no transaction is running
page@default The page if no other page is specified.
page@screen The page to show for this screen.
Chapter 12. The Terminal Servlet program 179

Properties and parameters reference
Request parameters
These parameters are set only when a request is made. You can also specify
any other property that can be set on a request, for example:
servlet@extendedLogging.
Parameter name Parameter value
request Set to ″send″ to send a screen to CICS or ″disconnect″ to
end a session
If required, a new terminal session is started.
display The name of a property that can be displayed, see
“Displayable properties” on page 181.
translateText Set to ″true″ to translate the characters and & to
< > and & respectively. This is used when
text is displayed.
transaction The transaction ID of a transaction to be started. This is
only used if the request is ″send″ and the terminal state
is idle.
ATI transactions cannot be started for the Terminal
Servlet.
transactionData Additional parameters to pass to a transaction. This is
only used if the request is ″send″ and the terminal state
is idle, and a transaction was specified.
DFH_CURSOR The field where the screen cursor should be placed, as a
field index (a number), or the name of the field, if a
screen handler bean is available for the current screen.
DFH_ENTER,
DFH_CLEAR, DFH_PA1 -
3, DFH_PF1 - 24
This parameter name must be in upper case.
The value is ignored.
Use one of these parameters to specify the AID key to
be sent to CICS. This must be in upper case.
A field index The text to be set in the field.
Use to set the contents of a field when you know the
field index.
usingSession Set to false if no terminal session is required.
180 CICS Transaction Gateway: UNIX Administration
If this parameter is set, any terminal used for this
request is discarded after use.

Parameter name Parameter value
matchOnIdle Set to false by default.
Properties and parameters reference
Normally the servlet only attempts to find a
ScreenHandler for the current screen when the terminal
state is ‘client’, that is, a conversational or
pseudo-conversational transaction is expecting a
response. Setting this property to true causes the servlet
to check the current ScreenHandler every time the
screen changes regardless of the state. You may want to
do this if you have transactions that use BMS maps, but
which are not conversational or pseudo-conversational.
If you have a large number of ScreenHandlers, the
servlet may run more slowly when this property is set
to true. For this reason, the default value is false.
In addition, if a Screen Handler bean is available for the current screen, you
can set any properties on that bean by specifying them in the request. For
beans generated by BMSMapConvert, the field names defined in the BMS
map are properties that can be set to the required text in the field.
Displayable properties
The following table shows the values that can be specified for the ″display″
request parameter or used for variable substitution, see “Using variable
substitution” on page 174.
Display values Displays
none Nothing. Use to suppress output from a
server-side include.
screen The screen - as part of an HTML form.
errorMessage If an error has occurred, the error
message.
errorCause If an error has occurred, further
information about the error.
DFH_CURSOR The name of the field where the cursor is,
if it can be determined, otherwise the
field index.
a field index The field text
a screen handler property name The value of the property if it can be
determined.
any of the servlet configuration properties The value of the property for the current
listed above
servlet instance.
Chapter 12. The Terminal Servlet program 181

Properties and parameters reference
Display values Displays
any page mapping property The value of the property for the current
servlet instance.
any request parameter, except for
″request″ and ″display″
The value of the property for the current
request.
pool@connectedTerminals The current number of connected
terminals, for this servlet instance.
pool@freeTerminals The current number of connected
terminals that are not in use, for this
servlet instance.
pool@terminalsInUse The current number of terminals allocated
to users, for this servlet instance.
CICS Transaction Server for z/OS Web Interface
The CICS Web Interface, included in CICS Transaction Server for z/OS
Version 1.2 and above, is a collection of transactions and programs supporting
direct access to CICS transaction processing services from Web browsers.
If you have generated HTML templates for use by the CICS Web Interface,
they can also be used as HTML templates by the Terminal Servlet. You will
have to make some changes to invoke the servlet instead of the CICS Web
Interface, but the format is basically the same.
To use the template file:
1. Copy the template file to a directory on the Web server.
2. Edit it to change the action to /servlet/TerminalServlet and add
a hidden element with name ″request″ and the value ″send″.
3. Generate a Map class and Screen Handler bean for the BMS map that the
HTML template refers to.
4. Compile the generated Java source files.
5. Copy the compiled class files to a suitable directory on the Web server.
6. Set the servlet property pool@handlerPath so that it will load the new
classes.
7. Set a page mapping property to associate the new Screen Handler bean
with the HTML template file.
182 CICS Transaction Gateway: UNIX Administration

Chapter 13. Problem determination and problem solving
Preliminary checks
Most problems in a CICS Transaction Gateway system are caused by one of
the following:
v User errors
v Programming errors
v Configuration errors.
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?
See “Configure your programming environment” on page 48 for
information on setting CLASSPATH.
The CLASSPATH is displayed at the top of the CICS Transaction Gateway
trace output. See “Starting the Gateway with user-specified options” on
page 132 for information on starting the Gateway daemon with tracing
enabled.
v Is the environment configured correctly?
Refer to the documents listed under “Sample configuration documents” on
page 238.
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 you
specified in servername.
v Are there any messages explaining the failure?
See “Messages” on page 184.
v Are there any Java exceptions?
See “Java exceptions” on page 192.
v Does the problem occur only at certain times?
© Copyright IBM Corp. 1996, 2002 183

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Problem determination
This might be because the system is heavily loaded at those times; See
“java.lang.OutOfMemory exception” on page 193 for more information.
v Can you re-create the failure?
What to do next
If you think the problem is with the CICS Transaction Gateway, see
“Diagnosing common problems: Gateway daemon” on page 188, or
“Diagnosing common problems: Client daemon” on page 203 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 212 for information on how to contact IBM.
See “Documenting problems” on page 213 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 with the Gateway daemon
Messages
The Gateway daemon writes log messages to standard output (stdout) orto
standard error (stderr). If Gateway daemon tracing is enabled, it also writes
log messages to the trace output file.
Messages have the format:
CCLnnnnt:
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,
regardless of their type, you can use a command like the following:
ctgstart 1>&
Refer to the documentation for your operating system for more information
on redirecting output.
See CICS Transaction Gateway: Gateway Messages for an explanation of all CICS
Transaction Gateway messages.
184 CICS Transaction Gateway: UNIX Administration

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 23.
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.
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 23. 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“Application tracing”
on page 186 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:
Problems with the Gateway daemon
Chapter 13. Problem determination and problem solving 185

|
|
|
|
|
|
|
Problems with the Gateway daemon
ctgstart -x
If you used the configuration tool to configure CICS Transaction Gateway, the
default destination for trace output is the CTG.TRC file in the
/bin subdirectory. 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.
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.
For more information on starting the Gateway daemon with trace options, see
“Starting the Gateway” on page 132.
For more information on performance considerations, see Chapter 8,
“Performance” on page 125.
Application tracing
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 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
You cannot enable JNI trace through the configuration tool. Use one of the
following methods to enable it:
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.
v While the CICS Transaction Gateway is running, use the system
administration functions. You must have enabled the TCPAdmin protocol
186 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Problems with the Gateway daemon
handler (see “TCPAdmin protocol settings” on page 64). See “Administering
your system” on page 135 for details of how to enable JNI trace
dynamically.
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
Using the CTG_JNI_TRACE environment variable to enable JNI trace is
supported only for migration purposes.
J2EE Tracing
Refer to “Tracing” on page 86 for information on using the tracing function
provided with the ECI and EPI resource adapters.
Servlet tracing and logging in WebSphere
IBM WebSphere Application Server provides the Advanced Administrative
Console to simplify the tasks associated with managing applications.
To enable servlet tracing in WebSphere do the following:
1. Configure WebSphere to send standard output and standard error to a file
of your choice:
In the Administrative Console, select the application server in which you
want to enable tracing. Under the General tab there are text-entry boxes
labelled Standard output and Standard error. You can type filenames in
these boxes to override the default destinations.
2. Enable tracing in the application:
v For the CICS Transaction Gateway Terminal Servlet, use the
servlet@debug property to enable tracing.
For more information see “Properties and parameters reference” on
page 176.
v For user-written applications, use Java directives to enable tracing. You
can type these in the Command line arguments box in the
Administrative Console. Use the same format for Java directives as in a
java command line call. For example, to enable full debug tracing, type
-Dgateway.T=on as the first command line argument.
See ″Tracing in Java client programs″ in the CICS Transaction Gateway:
Programming Guide book for further information on Java directives for
tracing.
Chapter 13. Problem determination and problem solving 187

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Problems with the Gateway daemon
3. Click on the Apply button, to update the WebSphere settings, and run the
servlet.
When a servlet runs, WebSphere writes logging information to the same
destination as standard output. This information includes start times, stop
times, and any error messages. For the CICS Transaction Gateway Terminal
Servlet, use the servlet@extendedLogging property to enable extended
logging. If you enabled extended logging, the Terminal Servlet writes to the
log every time it receives a request. This can provide useful information for
diagnosing problems but it reduces performance.
You can enable both tracing, and extended logging, while the Terminal Servlet
is running. For more information on Terminal Servlet properties see
“Properties and parameters reference” on page 176.
Diagnosing common problems: Gateway daemon
Problems running the configuration tool
Task Guide loses focus
Under some JVMs on the Windows and UNIX operating systems, you
might have problems when entering the name for a new server in the
Task Guide. If the text box loses focus after each key press, click the Next
button to move onto the next panel and then click the Back button to
return. You should now be able to input text normally. This is a JVM
problem.
Task Guide restrictions under UTF8 and IBM-eucJP locales
The Task Guide does not run correctly under the UTF8 and IBM-eucJP
locales on the AIX, HP-UX and Solaris operating systems. Table 10 shows
the combination of platforms, locales and JREs affected:
Table 10.
Platform Locale JRE Notes
AIX UTF8
IBM-eucJP
IBM 1.3 —
HP-UX UTF8 HP-UX See the HP-UX JRE
release notes on
supported locales.
Solaris UTF8 1.3 —
Chinese, Japanese or Korean characters do not display correctly
To display Chinese, Japanese or Korean characters correctly on the
Windows operating system, set the system locale to Chinese, Japanese or
188 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems: Gateway daemon
Korean. If characters still do not display correctly, install the relevant
world type font package. You can download world type font packages
from the following site:
http://www.ibm.com/developerworks/java/jdk/linux130/
The Gateway daemon fails to find Turkish configuration settings
When you run the configuration tool under a Turkish locale for the first
time, by default the configuration settings are saved in file CTG.INI.ini.
Rename the file to CTG.INI to allow the Gateway daemon to find the
settings automatically. You only have to do this once, when the
configuration tool is first run.
The configuration tool fails to launch under Turkish and the Solaris 1.3.0
JVM
This is a known problem with the Solaris 1.3.0 JVM and has been raised
under SunBugs 4380798 and 4346718. A workaround is detailed under
SunBug 4380798 in the Sun Java Bug Database; to access this, go to
http://java.sun.com/, follow the link to Online Support and search the
Bug Database for 4380798.
Problems running the configuration tool in Turkish under the HP-UX JREs
Running the tool under HP-UX JRE 1.3 results in messages saying that
fonts are not found. Despite this, Turkish characters display correctly.
Codepage problems
A Gateway daemon trace shows the codepage in which the JVM is running. It
is displayed in the System Properties section at the top of the trace. Refer to
Appendix A, “Data conversion when using the Client daemon and a CICS
server” on page 225 for information on finding the codepage 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 185
for information on tracing the Gateway daemon and the application. See
“Tracing” on page 195 for information on tracing the Client daemon, and
“Diagnosing common problems: Client daemon” on page 203 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 206, 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 1.3 you can send a SIGQUIT (-3) signal to a Java process to make it
Chapter 13. Problem determination and problem solving 189

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems: Gateway daemon
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.
Gateway daemon running on in-use Solaris 8 ports
On Solaris 8 it is possible to open a handler on an IP port that is being used
by another system server process, such as FTP or Telnet. This is a known
problem with Solaris 8 and Java; see Sunbug ID 4511442.
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 variable. If this does not give you enough information to
diagnose the problem, obtain a standard trace and contact your IBM support
organization.
SSLight:
When starting the CICS Transaction Gateway: The following message is issued
when starting the Gateway:
CCL6525W: Unable to start handler for the ssl: protocol.
[java.lang.ClassNotFoundException:
server KeyRing class name]
This message shows that the Gateway could not load the server KeyRing
class. Start the Gateway with stack tracing enabled. Check that the
CLASSPATH variable, which is displayed at the top of the trace output,
includes an entry for the directory that contains the class. Also check that the
CLASSPATH includes an entry for file cfwk.zip. If the Gateway cannot find
this file, it cannot load the KeyRing files.
You specify the name of the server KeyRing class in the KeyRing classname
field in the SSL protocol settings panel in the configuration tool. Do not
190 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
include the directory or file extension when you specify the KeyRing class
name. The CLASSPATH should include an entry for the directory that
contains the KeyRing class.
In a user application: The API call
SslJavaGateway.setKeyRing("ClientKeyRingName", "thePassword"); fails with
the following error in a user application:
java.lang.NoClassDefFoundError: com/ibm/sslight/SSLightKeyRing
Check that the CLASSPATH variable includes an entry for file cfwk.zip. This
file is supplied with the CICS Transaction Gateway.
JSSE:
Diagnosing common problems: Gateway daemon
JSSE assumed when using SSLight: If you pass a KeyRing or Keystore name to
CICS Transaction Gateway, but the class does not load, or cannot be found,
the Gateway daemon assumes that you are using JSSE and not SSLight.
iKeyMan locks with ″class not found″ exception: A message like the following is
received by the application:
java.lang.NoClassDefFoundError: com/ibm/security/pkcsutil/PKCSException
This happens if the IBM Java Cryptography Extension (JCE) package is not
installed. Ensure that you have installed the JCE supplied with CICS
Transaction Gateway in the ibm-jce.zip file. See “Installation” on page 104.
Application receives an ″access denied″ exception: A message like the following is
received by the application:
java.io.IOException: CCL6651E: 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, inCICS Transaction Gateway: Programming Guide, for more
information.
KeyStore name not recognized: Java interprets the back slash (\) character as a
parameter delimitter. If you used the back slash character as a directory
separator when entering the path name of the KeyStore file during
configuration, Java cannot recognize the name. Use either a forward slash (/)
character, or double back slash (\\) characters, as a separator in the path
name on all operating systems. For example:
/mykeys/jsse/keystore.jks
\\mykeys\\jsse\\keystore.jks
Chapter 13. Problem determination and problem solving 191

|
|
|
|
|
|
|
|
|
Diagnosing common problems: Gateway daemon
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 24 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 24. 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
occured. See “Tracing” on page 185 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:
CCL6664E: 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)
192 CICS Transaction Gateway: UNIX Administration

Diagnosing common problems: Gateway daemon
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″, inCICS 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.
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.
Too many threads: You can estimate the amount of virtual memory that is
required by the JVM as follows. Add together:
v the number of Connection Manager threads
v the number of Worker threads
v the number of background threads in use by Java
v the number of different network protocols in use
Then multiply this total by the size of the Java stack allocated to each thread
by the JVM.
In this calculation, assume that the number of active Java background threads
is about five. Refer to your Java documentation for a more accurate value. You
set the maximum numbers of Connection Manager threads and Worker
threads when you configure CICS Transaction Gateway. See “General
Gateway settings” on page 53 for more information.
The way that Java allocates memory depends on your JVM implementation.
Most JVMs allow you to control memory allocation by setting limits on the
sizes of the Java stack and the Java heap.
For more information on thread limits see Table 3 on page 17. For more
information on Java memory allocation refer to CICS Transaction Gateway:
Programming Guide and to your Java documentation.
Chapter 13. Problem determination and problem solving 193

|
|
|
Diagnosing common problems: Gateway daemon
On z/OS and UNIX operating systems the amount of memory available to
each process might be limited. See your operating system documentation for
more information.
Programs using beans included in earlier versions of CICS Transaction
Gateway
See “EPI beans provided in earlier versions of the CICS Transaction Gateway”
on page 224 for information on beans that are now provided only as sample
programs.
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: Gateway Messages book explains all of these
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 error log (which has a default name of CICSCLI.LOG) is an ASCII text file
that you can browse using a standard text editor.
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.
Console messages
Errors generated from within the Client daemon are displayed on the system
console There may be times when you do not want messages (client error and
security) to appear on the console; for example, if you leave the Client
daemon running unattended overnight. To disable the display of console
messages, enter the following command:
194 CICS Transaction Gateway: UNIX Administration

cicscli -n
Problems with the Client daemon
When the display of console messages is disabled, the messages are still
written to the Client daemon error log. To re-enable the display of console
messages, enter the following command.
cicscli -e
You can specify the -n parameter together with the -s parameter. The display
of console messages is enabled by default.
Messages from the Client daemon process
Messages from the the Client daemon process are sent to the system console
(/dev/console).
On the AIX operating system you can redirect these messages by using the
swcons command.
Tracing
The Client daemon tracing is a very 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 you 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.
You can specify which components of the Client daemon you want to trace.
You control this with the cicscli -m command, (see “cicscli command
reference” on page 145), or by specifying a list of components using the
configuration tool.
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 Maximum Client wrap size 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.
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.
Chapter 13. Problem determination and problem solving 195

Problems with the Client daemon
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.
See “Formatting the binary trace file” on page 197 for information on the trace
conversion utility.
Starting and stopping Client daemon tracing
To start Client daemon tracing, enter the cicscli command with the -d option,
for example:
cicscli -d=nnn
where nnn is optional, and is the maximum size in bytes of the data areas to
be traced. (The default value is 512.)
Note: It is recommended that you set at least -d=1000 to ensure that all
relevant data is included in the trace before sending it to your support
organization.
If you need to trace the Client daemon immediately from startup, you can
specify the -s and -d parameters together in the same cicscli command. For
example, the following command starts the connection to a CICS server with
the name CICSTCP, enables the trace function, and sets the maximum data
area size to be traced to 128 bytes:
cicscli -s=CICSTCP -d=128
You can specify which components are to be traced when you start tracing.
See “cicscli command reference” on page 145 for details.
To stop Client daemon tracing, enter the cicscli command with the -o option,
for example:
cicscli -o
The trace is also automatically stopped if you stop the Client daemon by
using the cicscli -x command.
Choosing which components to trace
ALL This option traces everything. It is the
preferred option; use it if performance allows,
and consider using the binary formatting tool
to filter information. See “Formatting the
binary trace file” on page 197 for details.
196 CICS Transaction Gateway: UNIX Administration

Problems with the Client daemon
API.1 and API.2 These trace the boundary between the user
application or Java classes, and the Client
daemon. Switching on API.2 automatically
switches on API.1 as well.
DRV.1 and DRV.2 The protocol drivers trace the boundary
between the Client daemon and the network
protocol. Specify the DRV.1 and API
components if you are not sure whether a
problem is inside the Client daemon, and you
want to minimize the impact on performance,
for example when trying to determine a
performance problem.
You can also specify these components to help
to determine which product is causing the
system to lock up.
CCL This component traces the main Client
daemon process. Specify the API and CCL
components if you believe that the problem is
within the Client daemon.
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.
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. You turn on wrapping of trace using the Maximum
Client wrap size configuration setting, where you 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, two files (called CICSCLI.BIN and
CICSCLI.WRP) are used. Each file can be up to half the size of the Maximum
Client wrap size value.
Formatting the binary trace file
You use the Binary Trace Formatter utility cicsftrc to convert the binary trace
file CICSCLI.TRC 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
Chapter 13. Problem determination and problem solving 197

Problems with the Client daemon
the text file. The components you can specify are the same as for cicscli
-m. 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 binary trace files to format and then
concatenate (that is, the binary files were created with a wrapping trace).
If no filename 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.
-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 driven from a
text file (CCLSUMTR.TXT) which is read in at initialization time. This
defines the set of trace points for which you want summary tracing, and
the type of trace point. As DetailFormat reaches each trace point, if it is
one of the ones read in from this file, a line is generated in the summary
file. Use as requested by your IBM support organization; see “Program
support” on page 212.
The formatter can produce a summary of API calls that the user program
makes, and show the progress of the calls through the Client daemon. Specify
the API.2 component to produce a summary trace. Figure 25 on page 199
shows an example. (The layout of your trace may be different, depending on
the contents of CCLSUMTR.TXT.)
198 CICS Transaction Gateway: UNIX 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 SKNIGHTS) send data: Length=89
[000000bf,0000017c] 12:08:32.330 [7391] CCL1040 using slot = Slotp->Ctrl.ConvId = 6
[000000bf,0000017c] 12:08:32.350 [7099] CCL1037 Sync ECI call, so waiting for a reply...
[00000089,00000063] 12:08:32.400 ▌[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,000000a4] 12:08:32.541 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,000000a4] 12:08:32.551 -S->[4410] CCL4411 TCP/IP (to SKNIGHTS) send data: Length=94
[00000089,00000168] 12:08:32.581

Problems with the Client daemon
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 SKNIGHTS |
+----------------------------------------------------------------------------------+
12345678901234567890123456789012345678901234567890123456789012345678901234567890
1 2 3 4 5 6 7 8
Figure 26. Screen capture from a formatted trace file
200 CICS Transaction Gateway: UNIX Administration

|
|
|
Problems with the Client daemon
The formatter lists the commands which built the screen, and shows an
approximation of the screen.
In Version 5.0 of CICS Transaction Gateway, the Binary Trace Formatter utility
has been enhanced to format SNA and MPTN data structures within TCP62
data flows.
Client daemon trace analysis
The Client daemon trace file records detailed information on all actions taken
during the execution of a particular activity. You can use this information in
your problem determination activities, and to help understand how the Client
daemon performs a particular function, for example, establishing a connection
to a CICS server.
If you cannot interpret the trace yourself, you should contact your IBM
support organization and forward the unformatted binary trace file.
Some sample traces are shown in “Sample Client daemon trace” on page 202.
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.
[number]
A number to aid 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. These trace messages are explained in
CICS Transaction Gateway: Gateway Messages.
data
Some trace entries include a dump of key data blocks in addition to the
trace message.
Chapter 13. Problem determination and problem solving 201

Problems with the Client daemon
Sample Client daemon trace: Figure 27 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 -d
cicscli -o
The trace was generated for an AIX Client daemon but is applicable to other
Client daemons.
17:03:57.580 [0000080c,00000908] [1007] TRC:▌CCL1042▐ *** CICS Client for AIX v5.0 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=’* ’, Codepage=819
...
...
...
17:04:00.625 [0000080c,00000908] [3102] CCL:▌CCL3114▐ CCIN install response: ApplId=’@0Z8AAAA’, Codepage=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 27. Sample Client daemon trace
Message ID Explanation
CCL1042 Start of trace message. The trace file is overwritten each time a
trace is started. You can delete the file when required. Check
the date and 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 “Starting and stopping
Client daemon tracing” on page 196).
CCL3251 The client sends a CCIN transaction to the server to install its
connection definition on the server.
CCL3238 Reply to message CCL3238, includes the conversation ID for
this conversation.
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
202 CICS Transaction Gateway: UNIX Administration

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 is the response to message CCL3114 with the
dynamically generated Appl ID.
CCL1043 End of trace message.
Figure 28 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 CTG.INI 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 v5.0 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:CCL3429 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 28. Client daemon trace: using an invalid port number
Problems with the Client daemon
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” on page 204
v “TCP/IP communication problems” on page 204
v “APPC communication problems” on page 205.
v “TCP62 communication problems” on page 205
v “Traps” on page 206
v “The Client daemon stops responding” on page 206
This section lists problems for all supported operating systems, to provide for
cases where client and server are on different operating systems.
For information on error messages, refer to CICS Transaction Gateway: Gateway
Messages.
Chapter 13. Problem determination and problem solving 203

Diagnosing common problems: Client daemon
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
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
CTG.INI 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 signon capable?
cicsterm attempts to install a signon capable terminal by default. If the -a
option works, the server probably does not support signon capable
terminals.
CICS servers require APAR fixes to support terminal signon capability; see
“Supported software” on page 23. 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 215 for general information about APARs.
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
204 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
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.
APPC communication problems
The following are solutions to problems that can occur when communicating
over APPC:
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 emulation. For information on which CICS servers support
EPI and hence CICS 3270 emulation, see Table 5 on page 28. 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 5 on page 28.
Solaris: Cannot load protocol driver ’CCLIBMSN’ message
No SNA driver is provided in this release. This message in your CICSCLI.LOG
file indicates that you are still trying to use SNA. Reconfigure your CTG.INI
file to use the TCP62 driver instead.
SNA error log: The SNA error log can help your support organization to
diagnose problems. The path to the file, if the product is installed to its
default location, on AIX is as follows: /var/sna/sna.err
TCP62 communication problems
Diagnosing common problems: Client daemon
CCL5820 TCP62: Attempt to open server ’server1’ which is a
duplicate of ’server2’
Multiple server definitions with identical combinations of Local LU, Partner
LU, and Mode name are not permitted in CTG.INI in the CICS Transaction
Gateway Version 5.0. This ensures that every connection that the CICS region
Chapter 13. Problem determination and problem solving 205

|
|
|
|
|
|
|
|
Diagnosing common problems: Client daemon
and the network protocol see is represented by a unique server definition in
the configuration file. Existing Client applications that use different server
names to send requests to the same CICS region continue to work if a user
exit is defined to redirect requests. A sample user exit that does this is
provided; see /samples/samples.txt.
Traps
AIX
If the Client daemon, or a user application terminates unexpectedly, it
may produce a core dump. You can get stack traces by attaching dbx to
the core dump. The procedure is similar to attaching dbx to a running
process—see “dbx tool” on page 207 for details. Consult your AIX
documentation 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 userid 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 189, 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 trace wrapping if you
do not want the trace file to get too large; see “Tracing” on page 185.) 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.
206 CICS Transaction Gateway: UNIX Administration

Diagnosing common problems: Client daemon
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?
All UNIX 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 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.
AIX
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
sknights 28266 1 0 11:06:46 pts/0 0:00 cclclnt
Chapter 13. Problem determination and problem solving 207

Diagnosing common problems: Client daemon
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:
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.
208 CICS Transaction Gateway: UNIX Administration

Diagnosing common problems: Client daemon
Ensure that the /etc/system file allows sufficient queue entries; see
“Configuring message queues” on page 44. 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
Information about these facilities is given in the Problem Determination books
for the individual products (see “CICS Transaction Server publications” on
page 239). 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 Transaction Gateway and CICS Universal Client
FAA CICS for OS/2
DFH CICS on System/390 ® and z/OS
ERZ Transaction Server for Windows NT Version 4.0, and TXSeries
AEG CICS for OS/400.
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 very difficult to analyze a problem in the communication part of a
system.
Chapter 13. Problem determination and problem solving 209

Communication problems
The Client daemon generates various messages associated with the use of the
supported communication protocols and the associated products. Refer to
CICS Transaction Gateway: 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.
IPCONFIG Displays all current TCP/IP network
configuration values. This is helpful if you
have to find out if an IP interface is active.
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.
210 CICS Transaction Gateway: UNIX Administration

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.
Communication problems
If you cannot acquire the connection, SNA is wrongly configured on the
product or the host.
IBM Communications Server for AIX ® : IBM Communications Server for
AIX writes a log file called sna.err, in /var/sna. This text file can help you to
diagnose communications errors. The IBM support organization needs the file
if you have SNA errors that you cannot resolve.
Follow these steps to interpret sense data:
1. Enter the command smitty sna to start the System Management Interface
Tool (SMIT).
2. Select Problem Determination Aids.
3. Select Show SNA Sense Code information.
4. Type the sense code into the panel to see a description of the code.
Chapter 13. Problem determination and problem solving 211

Program Support
Program support
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/ts/cics/
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
212 CICS Transaction Gateway: UNIX Administration

Program Support
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 216. If the RETAIN search is unsuccessful, the
problem is passed on to a Level-2 representative 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 215. 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 216.
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.
Chapter 13. Problem determination and problem solving 213

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Program Support
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.
v A 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 5.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.
214 CICS Transaction Gateway: UNIX Administration

Program Support
– Severity level 4 indicates that you are able to use the program with the
problem causing negligible hindrance.
When deciding the severity of the problem, take care to categorize it
correctly, as the procedures followed by the support organization depend
on the severity level supplied.
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.
v If you upload files to a mainframe system, do so in binary rather than
ASCII format.
APARs and fixes
Once 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 in time, 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
Chapter 13. Problem determination and problem solving 215

Program Support
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/details.
216 CICS Transaction Gateway: UNIX Administration

Chapter 14. Migration
This chapter 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. Topics covered include:
v “The configuration conversion tool”
v “Migrating from CICS Transaction Gateway Version 4” on page 218
v “Migrating from CICS Universal Client, or CICS Transaction Gateway,
Version 3” on page 219
v “Migrating from CICS Gateway for Java” on page 219
v “Migrating from the CICS Internet Gateway on AIX” on page 220
v “Configuring APPC for CICS Transaction Gateway for AIX” on page 224
v “EPI beans provided in earlier versions of the CICS Transaction Gateway”
on page 224
The configuration conversion tool
The configuration conversion tool (ctgconv) converts the configuration files of
versions of the following to the current format:
v CICS Transaction Gateway v3.0
v CICS Universal Client v3.0
If the CICS Transaction Gateway Version 5.0 installation upgrades your
existing product, the configuration conversion tool runs automatically if it
finds configuration files in the old format. If you have to uninstall the earlier
product first, or your configuration files cannot be found during the upgrade,
run ctgconv after installation.
The conversion tool converts the following:
Gateway.properties
Properties file of CICS Transaction Gateway Version 3.0 and CICS
Gateway for Java.
CICSCLI.INI
Client initialization file of CICS Clients Version 2 and Version 3.0.
The conversion tool produces one output file called CTG.INI by default.
Old files are renamed with the BAK extension.
© Copyright IBM Corp. 1996, 2002 217

|
|
|
|
|
|
Migration
Using the conversion tool
The parameters of ctgconv are:
ctgconv −c=file [−g=file] [−o=file]
For each parameter, file can be any of the following:
v A filename and extension; the /bin directory is assumed.
The extension must be INI, except for the CICS Transaction Gateway
Version 3.0 and CICS Gateway for Java input files, which have the
properties extension.
v A full pathname.
v A directory name (without a trailing /); the default filename is assumed.
−c=file
Specifies the Client initialization file to be converted. If file specifies a
directory, a filename of CICSCLI.INI is assumed.
If the parameter is not specified, the CICSCLI environment variable is
used to locate the Gateway initialization file. If CICSCLI is not set, the file
CICSCLI.INI, in the /bin subdirectory, is assumed.
−g=file
Specifies the Gateway.properties file to be converted. If you do not
specify this parameter, no Gateway section is created in CTG.INI.
−o=file
Specifies the pathname of the converted file. The default is CTG.INI, inthe
/bin subdirectory.
For help on using ctgconv, enter ctgconv −?
During conversion, the input files are renamed so that the last three characters
of the file extension become BAK. Any file with that name is overwritten, and
any output file that exists before the conversion is renamed in the same way.
A banner is inserted into the renamed files stating that they are obsolete.
Redundant parameters are removed from the old configuration files, and
other parameters are given new names in the converted file.
Migrating from CICS Transaction Gateway Version 4
Delete file /license before attempting to install Version 5.0.
This file contains license information for version 4 of the CICS Transaction
Gateway. ctginstall creates a directory called /license to
store license information for Version 5. If a file of the same name exists,
ctginstall cannot create the directory, and the installation fails.
218 CICS Transaction Gateway: UNIX Administration

Migrating from CICS Transaction Gateway Version 4
Migrating from CICS Universal Client, or CICS Transaction Gateway, Version 3
The following are not supported:
v CICSTELD
v SUNLINK (Solaris). APPC protocol is no longer supported in Solaris and
has been replaced by TCP62.
v The CICSCLI -f parameter
You might have customized versions of the following configuration files:
File Default Name
Keyboard mapping file CICSKEY.INI
Color mapping file CICSCOL.INI
Windows settings CICSTERM.INI
When you install CICS Transaction Gateway Version 5.0 your customized files
are preserved, even though CICS Universal Client Version 3.0 is deleted.
In CICS Transaction Gateway Version 5.0 the configuration file (CTG.INI),
replaces the Client initialization file (CICSCLI.INI).
The new file also replaces the Gateway.properties file.
These files are automatically converted to the correct format when you install
Version 5.0, if the files are found on upgrade. To convert the Gateway
initialization file, run the configuration conversion tool (ctgconv), see “The
configuration conversion tool” on page 217.
Migrating from CICS Gateway for Java
1. Take a copy of your Gateway.properties file.
2. Delete the CICS Gateway for Java.
3. Install the CICS Transaction Gateway Version 5.0.
4. Use the configuration conversion tool to convert your Gateway.properties
file; see “The configuration conversion tool” on page 217.
Change all import statements in your programs and recompile them. Change
all occurrences of:
import ibm.cics.jgate.client.* to: import com.ibm.ctg.client.*
import ibm.cics.jgate.epi.* to: import com.ibm.ctg.epi.*
import ibm.cics.jgate.security.* to: import com.ibm.ctg.security.*
Modify any programs written for the CICS Gateway for Java prior to Version
2.0.1 that use the Session interface. This is because the parameter to the
Chapter 14. Migration 219

|
|
|
|
|
|
Migrating from CICS Transaction Gateway Version 4
Session.handleReply method was changed to TerminalInterface instead of a
Terminal object. Change and then recompile your programs.
Due to a change in the ClientSecurity and ServerSecurity interfaces, any user
classes that implement these methods need to be changed. The TCP/IP
address of the remote computer is now passed to the methods called to
generate handshake data. An afterDecode method has also been added to
both interfaces. See Programming in Java, inCICS Transaction Gateway:
Programming Guide, for more information.
Migrating from the CICS Internet Gateway on AIX
This section describes how to migrate from using the CICS Internet Gateway
to using the Terminal Servlet.
Read Chapter 12, “The Terminal Servlet program” on page 163 before you
perform migration, to familiarize yourself with the concepts of the Terminal
Servlet.
The CICS Internet Gateway reads settings from a configuration file, which is
called cigd.env.
CICS Internet Gateway default settings
CICS Internet Gateway Terminal Servlet equivalent
Cursor The Cursor key equivalent. There is no
equivalent setting for the Terminal Servlet.
Instead, you can use JavaScript to set the
position of the cursor. To allow this, set the
servlet property screen@cursoring to true.
Info Filename for the information file for the server
(for AIX and Windows NT). There is no
equivalent setting for the Terminal Servlet.
Error Filename for the error file for the server. There
is no equivalent setting for the Terminal
Servlet.
Trace Filename for the trace file for the server. There
is no equivalent setting for the Terminal
Servlet. Servlets write logging information to
the servlet log provided by the Web server.
See your Web server documentation to find
out where this file is. If trace is turned on it is
written to the standard output. Depending on
your Web server, this may be directed to a file.
220 CICS Transaction Gateway: UNIX Administration

MaxUsers The maximum number of users. The
equivalent servlet property is
pool@maxTerminals.
TimeOutCICS The “Wait for CICS ” timeout. The servlet
property servlet@allocateTimeout limits the
time that the servlet will wait for a terminal to
be connected to CICS. There is no limit on the
time the servlet will wait for CICS to respond
in other situations.
TimeOutGateway The “Wait for Gateway” timeout. There is no
equivalent setting for the Terminal Servlet.
TimeOutInternet The “Wait for Internet” timeout. The servlet
property pool@idleTimeout limits the time
that the servlet will let a terminal be unused
before it is disconnected.
CICS Internet Gateway override settings
Migrating from CICS Transaction Gateway Version 4
CICS Internet Gateway Terminal Servlet equivalent
AutoExit Normally, the Terminal Servlet does not
disconnect the terminal when a transaction
ends. If this is the behavior you want, set the
page mapping property page@idle to the URL
/servlet/TerminalServlet?request=disconnect,
replacing TerminalServlet with the name of an
instance of the Terminal Servlet on your Web
server.
ExitAid The Exit key equivalent. The servlet uses
Screen Handler beans to exit running
transactions. You can generate and customize
Screen Handler beans for specific CICS
screens, and you can create a default Screen
Handler that knows how to exit a range of
transactions. The supplied sample
DefaultScreenHandler exits using the AID PF3.
ExitPage The URL for the HTML exit page. Use the
page mapping property page@disconnected to
specify a page to be displayed when the
terminal is disconnected.
ImbedHTML Allows Imbedded HTML. The servlets default
behavior is to write out the contents of CICS
screens as is, that is, text taken from the CICS
screen is assumed to be correct HTML. If the
Chapter 14. Migration 221

Migrating from CICS Transaction Gateway Version 4
characters , or & are present on the CICS
screen, this may cause problems. To translate
the characters , and & to < > and
& respectively, set the request parameter
translateText to true. No translation is
performed when sending data to CICS.
Header The filename for the HTML header. There is
no equivalent setting for the Terminal Servlet.
Trailer Filename for the HTML trailer. There is no
equivalent setting for the Terminal Servlet.
GraphicKeys Display the keys as GIFs. There is no
equivalent setting for the Terminal Servlet.
PAKeys Display the PA keys. There is no equivalent
setting for the Terminal Servlet.
PFKey24 Display extra row of PF keys. There is no
equivalent setting for the Terminal Servlet.
Output from the Terminal Servlet is inserted
into a Web page that you provide. The sample
file epissam1.shtml is provided as a starting
point.
CICS Internet Gateway actions
The CICS Internet Gateway is invoked by an HTML form. To invoke the
Terminal Servlet instead, change the action to /servlet/servlet where
servlet is TerminalServlet or another name.
Query the current gateway settings
You can query the various servlet properties individually. See
“Displayable properties” on page 181 for details.
List the available CICS systems
The servlet does not provide this function. Each Terminal Servlet
instance can connect to only one CICS server. You should configure an
instance of Terminal Servlet for each CICS server that you want to
allow users to connect to.
Start a transaction
You must add a hidden element setting the name ″request″
to the value ″send″, as in Table 11
Table 11. Terminal Servlet equivalents of actions
CICS Internet Gateway Terminal Servlet equivalent
element name
SystemName None
222 CICS Transaction Gateway: UNIX Administration

Table 11. Terminal Servlet equivalents of actions (continued)
CICS Internet Gateway
element name
Terminal Servlet equivalent
TranName transaction
TranData transactionData
AutoExit page@idle=/servlet/TerminalServlet?request=disconnect
is equivalent to AutoExit=On
ExitAID None
ExitPage page@disconnected
ImbedHTML translateText=true is equivalent to ImbedHTML=Off
Anything else None
See “Properties and parameters reference” on page 176 for more information.
Administration functions
You can query the number of terminals that are in use and turn trace on and
off. However, these functions cannot be restricted to administrators.
Migrating from CICS Gateway for Lotus Notes
CICS Clients Version 2 included the CICS Gateway for Lotus Notes, also
known as CICS Link for Lotus. This is not available in CICS Transaction
Gateway Version 5.0.
For inter-operation of CICS and Lotus Notes ® , IBM recommends that you use
the MQSeries ® Enterprise Integrator, which offers these advantages over the
CICS Gateway for Lotus Notes:
v A common API that you can use to integrate Lotus Notes with IMS or
MQSeries as well as CICS
v Support for the EPI and ECI
v Use it straight from a Web browser connected to Lotus Domino
MQSeries Enterprise Integrator is included in MQSeries and CICS
Connections for Domino. For more information, visit the Web site at:
www.lotus.com/
and follow the Products link.
Migrating from CICS Transaction Gateway Version 4
Chapter 14. Migration 223

|
|
|
|
|
|
|
|
|
Migrating from CICS Transaction Gateway Version 4
Configuring APPC for CICS Transaction Gateway for AIX
A LU6.2 Side Information Profile (SIP) is not required for versions later than
3.0. Instead of the SIP, the Partner LU Alias Name, LocalLU Alias Name, and
Mode Name are used.
It is also no longer necessary to have another SIP named CICSCLI for
Automatic Transaction Initiation (ATI).
EPI beans provided in earlier versions of the CICS Transaction Gateway
These beans, which previously were provided as part of the CICS Transaction
Gateway product, are now included with the set of sample programs:
v EPIMonitor
v EPIScreenButtons
v EPIBasicScreenHandler
Include the archive \classes\ctgsamples.jar in the classpath
of any programs that use these beans. The EPIBasicScreenHandler bean
includes new functions, such as font and color selection, and an improved
layout.
224 CICS Transaction Gateway: UNIX Administration

Appendix A. Data conversion when using the Client
daemon and a CICS server
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/390 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.
Supported conversions
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 table has been extracted from Communicating from CICS on
System/390, SC33-1697. 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 intent is that other CICS servers will
provide equivalent support.
Arabic:
CCSID CPGID
ASCII 00864 00864 PC data: Arabic
01089 01089 ISO 8859-6: Arabic
01256 01256 MS Windows: Arabic
EBCDIC 00420 00420 Host: Arabic
© Copyright IBM Corp. 1996, 2002 225

Data conversion
Baltic Rim:
CCSID CPGID
ASCII 00921 00921 PC data: Latvia, Lithuania
01257 01257 MS Windows: Baltic Rim
EBCDIC 01112 01112 Host: Latvia, Lithuania
Cyrillic:
CCSID CPGID
ASCII 00866 00866 PC data: Cyrillic
00915 00915 ISO 8859-5: Cyrillic
01251 01251 MS Windows: Cyrillic
EBCDIC 01025 01025 Host: Cyrillic multilingual
Estonia:
CCSID CPGID
ASCII 00922 00922 PC data: Estonia
01257 01257 MS Windows: Baltic Rim
EBCDIC 01122 01122 Host: Estonia
Greek:
CCSID CPGID
ASCII 00869 00869 PC data: Greece
00813 00813 ISO 8859-7: Grek
01253 01253 MS Windows: Greek
EBCDIC 00875 00875 Host: Grek
Hebrew:
CCSID CPGID
ASCII 00856 00856 PC data: Hebrew
00916 00916 ISO 8859-8: Hebrew
01255 01255 MS Windows: Hebrew
EBCDIC 00424 00424 Host: Hebrew
Latin-1:
CCSID CPGID
ASCII 00437 00437 PC data: USA, many other countries
00819 00819 ISO 8859-1: Latin-1 countries
00850 00850 PC data: Latin-1 countries
01252 01252 MS Windows: Latin-1 countries
EBCDIC 00037 00037 Host: USA, Canada, etc
00273 00273 Host: Austria, Germany
00277 00277 Host: Denmark, Norway
00278 00278 Host: Finland, Sweden
00280 00280 Host: Italy
00284 00284 Host: Spain, Latin America (Spanish)
00285 00285 Host: United Kingdom
00297 00297 Host: France
00500 00500 Host: International Latin-1
00871 00871 Host: Iceland
01047 01047 Host: Latin-1 Open Systems
226 CICS Transaction Gateway: UNIX Administration

Latin-1 including euro support:
CCSID CPGID
ASCII 00858 00858 PC data: Latin-1 countries
05348 01252 MS Windows: Latin-1 countries, version 2
EBCDIC 01140 01140 Host: USA, Canada, etc
01141 01141 Host: Austria, Germany
01142 01142 Host: Denmark, Norway
01143 01143 Host: Finland, Sweden
01144 01144 Host: Italy
01145 01145 Host: Spain, Latin America (Spanish)
01146 01146 Host: United Kingdom
01147 01147 Host: France
01148 01148 Host: International Latin-1
01149 01149 Host: Iceland
Latin-2:
CCSID CPGID
ASCII 00852 00852 PC data: Latin-2 multilingual
00912 00912 ISO 8859-2: Latin-2 multilingual
01250 01250 MS windows: Latin-2
EBCDIC 00870 00870 Host: Latin-2 multilingual
Latin-5:
CCSID CPGID
ASCII 00857 00857 PC data: Latin-5 (Turkey)
00920 00920 ISO 8859-9: Latin-5 (Turkey)
01254 01254 MS Windows: Turkey
EBCDIC 01026 01026 Host: Latin-5 (Turkey)
Latin-9:
CCSID CPGID
ASCII 00923 00923 ISO 8859-15: Latin-9
EBCDIC 00924 00924 Host: Latin-9
Japanese:
CCSID CPGID
ASCII 00932 00897 PC data: SBCS
00301 PC data: DBCS
00942 01041 PC data: extended SBCS
00301 PC data: DBCS
00943 00897 PC data: SBCS
00941 PC data: DBCS for Open environment
00954 00895 G0: JIS X201 Roman
00952 G1: JIS X208-1990
00896 G2: JIS X201 Katakana
00953 G3: JIS X212
EBCDIC 00930 00290 Host: Katakana, extended SBCS
00300 Host: DBCS
00931 00037 Host: Latin-1, SBCS
Data conversion
Appendix A. Data conversion when using the Client daemon and a CICS server 227

Data conversion
00300 Host:DBCS
00939 01027 Host: Latin-1, extended SBCS
00300 Host: DBCS
Korea:
CCSID CPGID
ASCII 00934 00891 PC data: SBCS
00926 PC data: DBCS
00944 01040 PC data: extended SBCS
00926 PC data: DBCS
00949 01088 PC data: SBCS, IBM KS code
00951 PC data: DBCS, IBM KS code
00970 00367 G0: ASCII
00971 G1: KSC X5601-1989
01363 01126 MS Windows: Korean SBCS
01362 MS Windows: Korean DBCS
EBCDIC 00933 00833 Host: extended SBCS
00834 Host: DBCS
Simplified Chinese:
CCSID CPGID
ASCII 00946 01042 PC data: extended SBCS
00928 PC data: DBCS
01381 01115 PC data: extended SBCS, IBM GB
01380 PC data: DBCS, IBMGB
01383 00367 G0: ASCII
01382 G1: GB 2312-80 set
01386 01114 PC data: SBCS, S-Chinese GBK,
T-Chinese IBM BIG-5
01385 PC data: DBCS, S-Chinese GBK
EBCDIC 00935 00836 Host: extended SBCS
00837 Host: DBCS
Traditional Chinese:
CCSID CPGID
ASCII 00938 00904 PC data: SBCS
00927 PC data: DBCS
00948 01043 PC data: extended SBCS
00927 PC data: DBCS
00950 01114 PC data: SBCS, IBM BIG-5
00947 PC data: DBCS
00964 00367 G0: ASCII
00960 G1: CNS 11643 plane 1
00961 G2: CNS 11643 plane 2
EBCDIC 00937 00037 Host: Latin-1 SBCS
00835 Host: DBCS
228 CICS Transaction Gateway: UNIX Administration

Appendix B. Hardware and software
This chapter lists hardware requirements and supported software for all
operating systems on which the CICS Transaction Gateway runs.
Hardware requirements
This section discusses the disk space requirements on z/OS, and general
hardware requirements on distributed platforms.
Disk space requirements on z/OS
CICS Transaction Gateway is normally installed into a directory such as
/usr/lpp/ctg, in USS (see also “Installation path” on page x). In this case,
during installation, the uncompressed tar file is present in the /usr/lpp
directory. The HFS data set for this directory must be large enough to take the
25MB (40 cylinders) that this file occupies. You can delete the files once
installation is complete. Installation also requires 25MB (40 cylinders) in the
/tmp directory.
Once installed, CICS Transaction Gateway occupies 27MB. You need enough
disk space for CICS Transaction Gateway and any logging and tracing files.
IBM recommends that you use a separate HFS data set with a primary
allocation of 40 cylinders for CICS Transaction Gateway software. Increase this
to 50 cylinders if the logging and trace files will be stored in the same HFS
data set. Increase it further if many instances of CICS Transaction Gateway
will run, or if much logging is required. Alternatively, you can use a separate
HFS data set, with a primary allocation of 5 cylinders, for each instance of
CICS Transaction Gateway.
If you use the existing /usr/lpp HFS data set, ensure it has enough space to
take the CICS Transaction Gateway software.
Table 12. Hardware requirements on UNIX systems
AIX LINUX SOLARIS HP-UX
Processor v IBM RISC
System/6000 ®
v IBM RS/6000 ®
G5, G6, MP3000 or
above
SPARC PA-RISC 1.1 or 2.0
Scalable
POWERParallel
System (SP2).
© Copyright IBM Corp. 1996, 2002 229

Table 12. Hardware requirements on UNIX systems (continued)
AIX LINUX SOLARIS HP-UX
Terminals Any type of Any standard Any type of Any standard
terminal or telnet or X based terminal or telnet or X based
X/Terminal that terminal that can X/Terminal that terminal that can
can attach to the access Linux. can attach to the access HP-UX.
processor.
processor.
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB
Disk space 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB
for temporary files for temporary files for temporary files for temporary files
used during used during used during used during
installation. installation. installation. installation.
Table 13. Hardware requirements on Windows systems
Processor Any processor capable of running the appropriate
operating system and other prerequisite software.
Network adapters To connect workstations to the LAN, you need a
suitable adapter such as an ethernet adapter.
Memory At least 64 MB.
Disk space You need 30 MB of free disk space for your CICS
Transaction Gateway (including documentation in US
English only).
Supported software
The following products are supported.
You need a further 30 MB for temporary files used
during installation. At least 12 MB of this must be on
your system partition.
Operating systems
CICS Transaction Gateway is supported on the following operating systems:
v AIX V4.3.3 with Service Pack 25
v AIX 5.1
v HP-UX 11.0
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)
v Linux for S/390 - SuSE 7.0 (Kernel level 2.2.16)
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)
230 CICS Transaction Gateway: UNIX Administration

v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)
v OS/390 V2.10
v z/OS V1.2
v Windows XP Professional
v Windows 2000 Professional with a minimum of Service Pack 1
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a
minimum of Service Pack 1
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a
v Windows NT Server V4.0 with a minimum of Service Pack 6a.
Notes:
– Windows NT 4 Terminal Server is not supported
– The setting of multiple user interface languages, under Windows
2000 MultiLanguage Version, is not supported.
– If you plan to run CICS Transaction Gateway under load, and
using remote protocols, it is strongly recommended that you use
a server version, rather than a workstation version, of Windows.
Web browsers
v HTML/HTTP functions: Any browser that supports HTML V1.0 should
work with the product.
v Java Functions: Any JDK 1.1 compliant Web browser should work with the
product.
The CICS Transaction Gateway is supported with the following browsers:
v Microsoft Internet Explorer 5.0, 5.5 and 6.0
v Netscape Communicator 4.7 and 6.2
v HotJava Browser V 1.1 (for Solaris)
Note: Applets running within the JVM supplied with the Netscape
Communicator browser fail to make successful connections with the
CICS Transaction Gateway. Message number CCL6652E is returned to
the applet. Currently there is no solution to this problem.
Java applets are supported for compatibility with previous versions of
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.
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
Appendix B. Hardware and software 231

|
|
|
|
|
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 going in
as. Currently there is no solution to this problem.
JDK levels
CICS Transaction Gateway supports JDK levels 1.3 and 1.3.1 at the following
minimum service levels:
v AIX: IBM Java SDK 1.3 (service release 6)
v HP-UX: Java SDK 1.3.0.02
v Solaris: Sun Java SDK SE 1.3.0_04.
v z/OS: IBM Java SDK 1.3
If using the IBM Persistent Reusable JVM, you are recommended to run at a
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable
functionality of this JVM.
If using Java under DBCS code pages, especially IBM-939, install service
refresh 14 or later.
v Windows: IBM Java SDK 1.3 (service release 6)
JSSE
CICS Transaction Gateway supports JSSE in the the following environments:
v Standard Java runtime environment (JRE).
Only the IBM JSSE is supported:
– AIX: Install the JSSE package supplied with CICS Transaction Gateway
– HP-UX: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
– Linux for S/390: Install the JSSE package supplied with CICS Transaction
Gateway
– Solaris: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
– z/OS with JRE 1.3.1: includes a version of JSSE that CICS Transaction
Gateway supports
– Windows: Install the JSSE package supplied with CICS Transaction
Gateway
v WebSphere Application Server:
All supported levels have built in JSSE support.
CICS Transaction Gateway does not support the use of JSSE with applets.
CICS Servers
A CICS server runs real-time multi-user applications and manages the
associated resources and data. CICS Transaction Gateway is supported with
the following servers:
232 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
v CICS Transaction Server for z/OS V2.2
v CICS Transaction Server for z/OS V2.1 (with APAR PQ30168, for signon
capable terminals, applied)
v CICS Transaction Server for z/OS V1.3 with APAR PQ30168, for signon
capable terminals, applied.
v CICS for MVS/ESA V4.1, with communication through SNA. (with APAR
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for
EPI emulation. APAR PN79262 is needed for DBCS support.
v CICS for OS/400 V4.4
v CICS Transaction Server for OS/2 V4.1 with CSD 3
v CICS Transaction Server for VSE/ESA 1.1.0 (with APAR PQ30170, for
signon capable terminals, applied), or a minimum service level of 1.1.1
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)
v TXSeries V5.0 (Windows, AIX)
Web servers
Any web server that is supported by your application server should work
with the product.
Application servers
The CICS Transaction Gateway is supported with the following:
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,
AIX and Solaris.
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF
UQ99329 (Service Level W401030).
SNA communications
Customers wishing to use SNA communications should install one of the
following products:
Windows operating systems
Any one of:
v IBM eNetwork Communications Server V6.1, with a minimum of
service level 1
v IBM eNetwork Personal Communications V5.0, with a minimum of
service level 2
v IBM eNetwork Personal Communications V5.5
v Microsoft SNA Server V4.0 with a minimum of SP4
AIX
IBM eNetwork Communications Server V6.1, with a minimum of service
level 1 (AIX).
Appendix B. Hardware and software 233

|
|
SNA is not supported on other UNIX operating systems.
TCP/IP communications
TCP/IP support is provided by the operating system.
TCP62 communications
TCP62 support is provided by CICS Transaction Gateway.
Compilers and application development tools
CICS Transaction Gateway is supported with the following compilers and
application development tools:
AIX
v IBM C for AIX V4.4
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6
v IBM VisualAge C++ Professional V4.0
v IBM VisualAge C++ Professional V5.0 (requires AIX version 4.2 or later)
HP-UX
v HP ANSI C B.11.01, with a minimum of service level 7
v HP aC++ B.11.01, with a minimum of service level 6
Linux for S/390
v GNU compiler C runtime V2.95, with a minimum of service level 2
v GNU compiler C++ runtime V2.95, with a minimum of service level 2
Solaris
Sun WorkShop C++ V5.0
Note: The C++ compiler must have all available service patches applied.
Windows
v IBM VisualAge COBOL V3.0
v Microsoft Visual C++ V6.0
v Microsoft Visual Basic V6.0
v Microsoft Visual Basic Script (VBScript) V5.0
Note: The CICS Transaction Gateway does not support use of the COM
libraries with Microsoft Transaction Server (MTS), or the MTS
component of COM+.
Screen readers
The CICS Transaction Gateway is supported with JAWS.
234 CICS Transaction Gateway: UNIX Administration

|
|
|
Other tools
These tools are available for viewing the PDF online documents:
v Adobe Acrobat Reader V5.0
v GhostView V4.0 on Linux
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.
Appendix B. Hardware and software 235

236 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The product library and related literature
This chapter lists books on the CICS Transaction Gateway, and related topics.
It also discusses how you can view the online library supplied with the
product.
It consists of the following topics:
“CICS Transaction Gateway books” Read this for a list of all books provided
with the CICS Transaction Gateway.
“Sample configuration documents” on
page 238
Read this for information about a series of
PDF documents that provide step-by-step
guidance on configuring the CICS
Transaction Gateway.
“Redbooks” on page 239 Read this for details of other publications
that contain examples of client/server
configurations.
“Other Useful Books” on page 239 Read this for details of other relevant
publications.
“Obtaining books from IBM” on page 240 Read this for information on downloading
books and ordering hardcopy versions.
CICS Transaction Gateway books
v CICS Transaction Gateway: Windows Administration, SC34-6190
This book describes the administration of the CICS Transaction Gateway for
Windows.
v CICS Transaction Gateway: UNIX Administration, SC34-6139
This book describes the administration of the CICS Transaction Gateway for
UNIX operating systems.
v CICS Transaction Gateway: z/OS Administration, SC34-6191
This book describes the administration of the CICS Transaction Gateway for
z/OS.
v CICS Transaction Gateway: Gateway Messages
This online book lists and explains the error messages that can be generated
by CICS Transaction Gateway.
You cannot order this book.
v CICS Transaction Gateway: Programming Reference, SC34-6140
© Copyright IBM Corp. 1996, 2002 237

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The CICS Transaction Gateway
This book provides information on the APIs of the programming languages
supported by the CICS Transaction Gateway.
There are also additional HTML pages that contain JAVA programming
reference information.
v CICS Transaction Gateway: Programming Guide, SC34-6141
This introduction to programming for the CICS Transaction Gateway
provides the information that you need to allow non-CICS applications to
use CICS facilities in a client/server environment.
Sample configuration documents
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. .
The following scenarios are currently covered:
v Configuring CICS Transaction Gateway for Windows for Microsoft SNA
Server
v Configuring CICS Transaction Gateway for Windows for eNetwork Personal
Communications
v Configuring CICS Transaction Gateway for Windows for TCP62
v Configuring CICS Transaction Gateway for AIX for IBM eNetwork
Communications Server
v Configuring CICS Transaction Gateway for Windows for Communications
Server
v Configuring CICS Transaction Gateway for Terminal Servlets using
WebSphere Application Server for Windows
v Client security configuration
v Configuring CICS Transaction Gateway for WebSphere 4.01 using J2EE
v Configuring CICS Transaction Gateway 4.02 for WebSphere Application
Server on z/OS using J2EE
As more sample configuration documents become available, you can
download them from our Web site at:
www.ibm.com/software/ts/cics/
and follow the Download link.
238 CICS Transaction Gateway: UNIX Administration

Redbooks
Other Useful Books
The following International Technical Support Organization (ITSO) Redbook
publication contains many examples of client/server configurations:
v CICS Transaction Gateway V3.1 The WebSphere Connector for CICS, SG24-6133
This book supersedes the following book:
v Revealed! CICS Transaction Gateway with more CICS Clients Unmasked,
SG24-5277.
v Java Connectors for CICS: Featuring the J2EE Connector Architecture, SG24-6401.
This book provides information on developing J2EE applications.
See also:
v Securing Web Access to CICS, SG24–5756.
v Workload Management for Web Access to CICS, SG24–6118.
You can obtain ITSO Redbooks from a number of sources. For the latest
information, see:
www.ibm.com/redbooks/
CICS Transaction Server publications
Other publications
CICS interproduct communication
The following books describe the intercommunication facilities of the CICS
server products:
CICS Family: Interproduct Communication, SC34-6030
Transaction Server for Windows NT: Intercommunication, SC33-1882
CICS Transaction Server for z/OS: Intercommunication Guide, SC34-6005
CICS Transaction Server for VSE/ESA: Intercommunication Guide, SC33-1665
CICS for OS/400: Intercommunication, SC33-1388
TXSeries: CICS Intercommunication Guide, SC09-3900
CICS for OS/2: Intercommunication, SC33-1583
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:
Transaction Server for Windows NT: Problem Determination, GC33-1883
CICS Transaction Server for z/OS ® Problem Determination Guide, SC34-6002
The product library and related literature 239

Other publications
CICS Transaction Server for VSE/ESA Problem Determination Guide,
GC33-1663
CICS for OS/400 ® : Problem Determination, SC33-1384
TXSeries: CICS Problem Determination Guide, SC33-1565.
You can find information on CICS products at the following Web site:
www.ibm.com/software/ts/cics/
APPC-related publications
The following books are concerned with products providing APPC support:
IBM products
IBM Communications Server for AIX for AIX:
IBM Communications Server for AIX: Quick Beginnings, GC31-8583
IBM Communications Server for AIX: General Information, GC31-8584
IBM Communications Server for AIX: Administration, SC31-8586
IBM Communications Server for AIX: Administration Command Reference,
SC31-8587
Systems Network Architecture (SNA)
SNA Formats, GA27-3136
Systems Network Architecture Technical Overview, GC30-3073
TCP62–related publications
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
GC31–7073
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074
Obtaining books from IBM
For information on books you can download, visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link.
You can order hardcopy books:
v Through your IBM representative or the IBM branch office serving your
locality.
v By calling 1-800-879-2755 in the United States.
v From the Web site at:
www.ibm.com/shop/publications/order
240 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Accessibility
The English version of the CICS Transaction Gateway has been tested for
accessibility on the Windows operating system. The product is accessible.
Documentation
Download the CICS Information Center for an html version of the
documentation. Go to this Web page
www.ibm.com/software/ts/cics/
iKeyMan
Samples
and follow the Library link.
See this Web site for information:
www.tivoli.com
The samples are not accessible.
Configuration tool accessibility
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+letter
Certain actions have shortcuts assigned to them. Hold down the Ctrl key
and type the letter to do the action.
Ctrl+letter Action
C Copies the selected value.
N Creates a new configuration.
© Copyright IBM Corp. 1996, 2002 241

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Ctrl+letter Action
O Opens an existing configuration.
P Pastes.
S Saves the current configuration.
U Cuts the selected value.
V Pastes.
W Creates a new server definition.
X Cuts the selected value.
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 tree 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 tree is active.) Move up and down through the tree.
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.
Control+Page Up
Scroll left.
Control+Page Down
Scroll right.
Control+Tab
Use this (rather than Tab) on panels that contain a table to cycle between
the tree, objects on the panel, and the buttons. Use Control+Shift+Tab to
move backwards.
Enter
Activates a button in the Task Guide.
Escape
Closes the menu.
F2 Select and change an editable number field in a table, for example the
Bias value field on the Program definition for managing workload panel.
242 CICS Transaction Gateway: UNIX Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
F6 (Applies if the tree or the panel is active.) Toggles between the tree and
the panel.
F8 (Applies if the tree or the panel is active.) Allows you to gain control of
the split between the tree and 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
tree, increase the width of the panel).
v Press the right arrow key to move the split right (increase the width of
the tree, decrease the width of the 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.
Shift+Tab
If the cursor is on a field in the panel other than the first field, moves
backwards through the fields. Otherwise, toggles between the tree and the
panel.
Space
1. Activates a button.
2. Selects a checkbox.
3. Selects a node in the tree.
Tab
Cycles through the tree, fields in the panel, and the buttons.
Customizing colors and fonts
Use the Settings option on the menu to change colors and fonts. Settings are
not applied consistently on the Task Guide.
To make them more noticeable, the names of items that contain errors are
displayed in the original typeface, in red and underlined.
Using help
Screen readers read the entire page in the help window, rather than the area
required by a user who has pressed F1. Also, the help window is not
navigable by the keyboard. The solution is to open the help files, which are
html files, in a browser outside the configuration tool. The help file index is
cclhlp15.htm in directory:
Accessibility 243

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
/bin/resource/
where represents the directory containing the help files in these
languages:
Language
English html
German html_de
Spanish html_es
French html_fr
Italian html_it
Japanese html_ja
Korean html_ko
Turkish html_tr
Simplified Chinese html_zh
Task Guide
Screenreaders cannot read the Task Guide; do not use the Task Guide if you
use a screenreader. Use the menu in the configuration tool to add servers
(Tools —> New server). Use the tree structure to enable protocols that the
Java gateway will use.
244 CICS Transaction Gateway: UNIX 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.
A
abend. The termination of a task, job, or
subsystem because of an error condition that
recovery facilities cannot resolve.
APAR. (Authorized program analysis report.) A
report on the basis of which IBM supplies a fix
of a temporary corrective nature to elements of
function SYSMODs. APAR fixes are called
″corrective″ service because they are installed to
cure problems currently being experienced by an
installation. The APAR fix is usually in the form
of either a modification to a load module or an
update to card-image data. It is intended as a
temporary arrangement until a preventive service
(PTF) is issued to fix the problem permanently.
This PTF supersedes the APAR fix, and indeed
specifies this relationship on its ++VER
statement.
API. Application programming interface.
APING. A command used to verify an APPC
link.
APPC. Advanced program-to-program
communication. 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.
applet. A Java program that is downloaded to,
and executed on, a Web browser or network
computer. See also servlet.
applid. In CICS, a system initialization and
terminal control parameter that identifies the
CICS system to other remote systems.
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 facility that enables terminal
definitions to be created automatically in a CICS
server on request. The definition is deleted when
the client terminal is logged off.
automatic transaction initiation (ATI). The
process whereby a transaction request made
internally within a CICS system or network leads
to the scheduling of the transaction. An ATI
request from a CICS Transaction Gateway can
cause the initiation of a transaction in a CICS
server system.
B
beans. See JavaBeans.
BIND. 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.
C
CA. See certification authority.
CEDA. A CICS transaction that defines
resources online.
© Copyright IBM Corp. 1996, 2002 245

Glossary
certification authority. In computer security, an
organization that issues certificates. The
certification 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 External Call Interface (EXCI). An
application programming interface that enables a
program running on Z/OS, such as CICS
Transaction Gateway, to call a program running
in a CICS region. The programs can transfer data
between each other using a communication area.
Compare with External Call Interface (ECI).
CICS Gateway for Java. In CICS Universal
Clients Version 2, an interface between a Java
program and CICS that allows a Java-enabled
browser to dynamically download a Java Applet
and transparently access CICS data. This has
been replaced by the CICS Transaction Gateway.
CICS on open systems. A term used to refer
generically to the products: CICS for HP-UX,
CICS for Sun Solaris, TXSeries for AIX, TXSeries
for HP-UX, and TXSeries for Solaris.
CICS on System/390. A term used to refer
generically to the products CICS Transaction
Server for z/OS , CICS for MVS/ESA, CICS
Transaction Server for z/OS, CICS Transaction
Server for VSE/ESA, and CICS/VSE ® .
cicscli. A command that starts and stops the
Client daemon, checks the availability of servers,
and sets other options.
cicsprnt. A command that allows you to define
a printer terminal on the Client daemon
workstation. The command enables CICS
applications running on the server to direct
output to the client-attached printer.
cicsterm. A command that provides 3270
emulation and enables connection to a CICS
region.
246 CICS Transaction Gateway: UNIX Administration
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. An environment variable that tells
the JVM and other Java applications where to
find the class libraries, including user-defined
class libraries.
Client API. On distributed platforms running
non-Java applications, the interface between the
Client application and the Client daemon.
client application. A user application, written in
a supported programming language other than
Java, that communicates directly with the Client
daemon.
Client daemon. The Client daemon (process
cclclnt) exists only on distributed platforms. 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. A distributed application design
model, in which the client sends a request to its
partner, the server, which executes the request
and returns the results to the client. This design
model is associated typically with cooperative
processing.
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. File CICSCOL.INI used by
the CICS Transaction Gateway to customize the
3270 screen color attributes on client
workstations.
COMMAREA. A communication area that is
used for passing data both between programs
within a transaction and between transactions.

Common Object Request Broker Architecture
(CORBA). An industry standard for an interface
definition language that enables different object
request brokers to interoperate.
configuration file. The file CTG.INI containing
information telling CICS Transaction Gateway
about the CICS servers that it can connect to, and
the communication protocols to use.
configuration tool. A graphical user interface
that allows you to configure the CICS
Transaction Gateway.
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.
control table. In CICS, a storage area used to
describe or define the configuration or operation
of the system.
conversation. The communication between a
CICS Transaction Gateway and a CICS server. In
APPC, a connection between two transaction
programs over an LU-LU session that allows
them to communicate with each other while
processing a transaction. See also session.
conversation security. In APPC, a process that
allows validation of a user ID or group ID and
password before establishing a connection.
cooperative processing. A subset of distributed
processing, in which at least the user interface
(presentation) aspect of the application runs on a
programmable workstation.
CORBA. See Common Object Request Broker
Architecture.
ctgstart. A command that starts the gateway
daemon.
D
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.
Glossary
dependent LU. A logical unit (LU) that can
receive, but not send a BIND, and which
supports only single sessions. See BIND.
digital certificate. A form of personal
identification that can be verified electronically.
Only the certificate owner who holds the
corresponding private key can present a
certificate for authentication through a Web
browser session. Anyone can verify that the
certificate is valid by using a readily available
public key.
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. A link that enables
an application program running on one CICS
system to link to another application program
running in another CICS system.
Glossary 247

Glossary
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.
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.
E
EBCDIC. Extended binary-coded decimal
interchange code. A coded character set of 256
8-bit characters developed for the representation
of textual data.
ECI. See external call interface.
emulator, 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. In the CICS Transaction
Gateway the terminal emulation function allows
client workstations to run CICS transactions that
use 3270 data flows.
248 CICS Transaction Gateway: UNIX Administration
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.
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 10–megabit or 100–megabit
baseband 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 CICS External Call Interface.
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.
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.
F
firewall. A configuration of software that
prevents unauthorized traffic between a trusted
network and an untrusted network.

G
gateway. A device that connects two dissimilar
LANs, or that connects a LAN to a wide area
network (WAN), midrange computer, or
mainframe computer. A gateway device has its
own processor and memory and may perform
protocol conversion. A gateway handles multiple
communication sessions simultaneously.
gateway classes. The interface for Java Client
applications to connect to the Gateway daemon.
The Gateway classes, which are supplied with
the CICS Transaction Gateway, must be in the
classpath for Java Client applications to run.
gateway daemon. Used only in remote mode,
the Gateway daemon listens on protocols defined
in CTG.INI for gateway requests from remote
Java client applications. It issues these requests to
the Client daemon on distributed platforms, and
directly to CICS over the EXCI on z/OS. The
Gateway daemon runs the protocol listener
threads, the worker threads and the connection
manager threads. It uses the GATEWAY section
of CTG.INI (and on z/OS the ctgenvvar script)
for its configuration.
H
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 in an internet.
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
domain name of a host.
HTTP. In the Internet suite of protocols, the
protocol that is used to transfer and display
hypertext and XML documents.
HTTPS. A TCP/IP protocol that World Wide
Web servers and Web browsers use to transfer
and display documents secured by SSL.
I
iKeyman. A tool supplied with the Gateway for
maintaining digital certificates for SSLight and
JSSE.
independent LU. A logical unit (LU) that can
both send and receive a BIND, and which
supports single, parallel, and multiple sessions.
See BIND.
internet. A collection of networks
interconnected by a set of routers that allow
them to function as a single, large network.
Contrast with Internet.
Internet. The internet administered by the
Internet Architecture Board (IAB), consisting of
large national backbone networks and many
regional and campus networks all over the
world. The Internet uses the Internet suite of
protocols.
Internet address. See IP address.
Glossary
Internet Architecture Board. The technical body
that oversees the development of the internet
suite of protocols known as TCP/IP.
Internet Packet Exchange (IPX). In Novell
NetWare LANs, a communication protocol that
sends data packets to requested destinations.
Internet Protocol (IP). In TCP/IP, a protocol
that routes data from its source to its destination
in an Internet environment.
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.
intranet. A private network that integrates
Internet standards and applications (such as Web
browsers) with an organization’s existing
Glossary 249

Glossary
computer networking infrastructure. Compare
with Internet and internet.
IP. Internet Protocol.
IPX. Internet Packet Exchange.
J
J2EE. (Java 2 Platform, Enterprise Edition.) 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.
Java. An object-oriented programming language
for portable interpretive code that supports
interaction among remote objects.
JavaBeans. A platform-independent, software
component technology for building reusable Java
components called beans. Once built, these beans
can be made available for use by other software
engineers or they can be used in Java
applications. Also, using JavaBeans, software
engineers can manipulate and assemble beans in
a graphical drag-and-drop development
environment.
Java client application. A Java application,
servlet or applet that communicates with the
Gateway classes.
Java development kit (JDK). A software
package that can be used to write, compile,
debug, and run Java applets and applications.
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 Secure Socket Extension (JSSE). An
implementation of SSL, written in Java, and
supported by CICS Transaction Gateway.
250 CICS Transaction Gateway: UNIX Administration
Java Virtual Machine (JVM). A software
implementation of a processor that runs
compiled Java code (applets and applications).
JDK. See Java development kit (JDK).
JNI. See Java Native Interface (JNI).
JSSE. See Java Secure Socket Extension (JSSE).
JVM. See Java Virtual Machine (JVM).
K
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. The default keyboard mapping file for
the CICS Transaction Gateway is CICSKEY.INI.
KeyRing or KeyStore. In computer security, a
file that contains public keys, private keys,
trusted roots, and certificates.
L
LAN. See local area network.
local area network (LAN). A network of
workstations, or terminals, or both, where all the
connected systems are relatively near to each
other. See wide area network.
local mode. Describes a Java Client application
using the Gateway local protocol. The Gateway
daemon is not used in local mode; on distributed
platforms, the Gateway classes interface directly
with the Client daemon API, and with the EXCI
on z/OS. See remote mode.
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.
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.
LU-LU session type 6.2. In SNA, a type of
session for communication between peer
systems. Synonymous with APPC protocol.
LU 6.2. See APPC.
M
MAC. Medium access control.
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.
N
name server. In TCP/IP, synonym for Domain
Name Server In Internet communications, the
host that translates host names into their
respective internet addresses when requested by
the hosts on the network A physical device, and
its associated software, that enables a processor
or controller to be connected to a network.
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.
O
object. In object-oriented programming, a
concrete realization of a class that consists of
data and the operations associated with that
data.
object request broker (ORB). Software that
serves as an intermediary by transparently
enabling objects to exchange requests and
responses.
OO. Object-oriented.
P
Glossary
pacing. A technique by which a receiving
station controls the rate of transmission of a
sending station to prevent overrun.
packet internet groper (PING). In Internet
communications, a program used in TCP/IP
networks to test the ability to reach destinations
Glossary 251

Glossary
by sending the destinations an Internet Control
Message Protocol (ICMP) echo request and
waiting for a reply.
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. Packet internet groper. The command
that sends an ICMP Echo Request packet to a
gateway, router, or host with the expectation of
receiving 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. Primary logical unit. 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.
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 (LU) that contains the primary half-session
for a particular LU-LU session. Contrast with
secondary logical unit. See also logical unit.
Note: A particular logical unit may contain
primary and secondary half-sessions for
different active LU-LU sessions.
protocol boundary. The signals and rules
governing interactions between two components
within a node.
252 CICS Transaction Gateway: UNIX Administration
R
RACF. Resource Access Control Facility. An IBM
licensed program that provides access control by
identifying users to the system; verifying users of
the system; authorizing access to protected
resources; logging detected, unauthorized
attempts to enter the system; and logging
detected accesses to protected resources.
region. A physical instance of a CICS server.
remote mode. Describes a Java Client
application using a Gateway network protocol to
connect to the Gateway daemon. See local mode.
remote procedure call (RPC). Remote procedure
calls are analogous to the standard procedure
calls used in modern programming, providing
modularity and reducing code size. The main
difference between standard procedure calls and
remote procedure calls is that in a remote
procedure call, the called procedure is being
executed by a different process than the caller. To
the calling procedure, a remote procedure call
looks the same as a call to a local procedure.
When a program makes a remote procedure call
to a remote application, the procedure’s
parameters are automatically bundled into a
request message, which is then sent to the
remote program or system.
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.
RU. Request unit. Response unit.

RPC. See remote procedure call.
S
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.
servlet. A Java servlets program that run on a
Web server machine, unlike Java applets, which
are downloaded to a Web browser. Java servlets
have become popular as a replacement for CGI
(Common Gateway Interface) programs.
session. In SNA, a logical connection between
two network addressable units (NAUs) that can
be activated, tailored to provide various
protocols, and deactivated as requested. The
session activation request and response can
determine options for such things as rate and
concurrency of data exchange, control of
contention and error recovery, and characteristics
of the data stream. Sessions compete for network
resources, such as links within the path control
network. For routing purposes, each session is
identified by the network or local addresses of
the session partners. See LU-LU session, LU-LU
session type.
session limit. In SNA, the maximum number of
concurrently active LU-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.
signon capable terminal. A signon capable
terminal allows signon transactions, either
CICS-supplied (CESN) or user-written, to be run.
Contrast with signon incapable terminal.
SIT (system initialization table). A table
containing parameters used to start a CICS
control region.
SNA gateway. A gateway that handles multiple
APPC communication sessions simultaneously.
See gateway.
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.
SSL. See Secure Sockets Layer (SSL).
Glossary
SSLight. An implementation of SSL, written in
Java, and supported by CICS Transaction
Gateway.
System Management Interface Tool (SMIT). In
the AIX operating system, a set of menu-driven
services that facilitate the performance of system
tasks such as installation, management,
configuration, and diagnosis.
standard error. In many workstation-based
operating systems, the output stream to which
error messages or diagnostic messages are sent.
subnet. In TCP/IP, a part of a network that is
identified by a portion of the Internet address.
Synonym for subnetwork.
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.
Systems Network Architecture (SNA). The
description of the logical structure, formats,
protocols, and operational sequences for
Glossary 253

Glossary
transmitting information units through, and
controlling the configuration and operation of,
networks.
System SSL. An implementation of SSL,
supported by CICS Transaction Gateway on
z/OS. Written in native code, it supports
hardware encryption technology available to
z/OS, and can be used only for SSL servers on
that operating system.
T
Taskguide. A function of the configuration tool
that provides step-by-step guidance to
configuring your CICS Transaction Gateway. .
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. Transmission Control Protocol/Internet
Protocol.
TCP/IP address. An address that uniquely
identifies a machine on a network. A machine
can have several threads of execution running at
the same time; a TCP/IP port uniquely identifies
a particular thread.
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.
Terminal Servlet. A Java program that allows
you to use a Web browser as an emulator for a
3270 CICS application running on any CICS
server.
thread. A stream of computer instructions that
is in control of a process. A multithread process
begins with one stream of instructions (one
thread) and may later create other instruction
streams to perform tasks.
254 CICS Transaction Gateway: UNIX Administration
token ring. A network with a ring topology that
passes tokens from one attaching device to
another; for example, the IBM Token-Ring
network.
trace. A record of data that provides a history of
events that occurred in a system. The process of
recording the sequence in which the statements
in a program are executed and, optionally, are
the values of the program variables used in the
statements.
transaction program. A program that uses the
APPC application program interface (API) to
communicate with a partner application program
in the same node or at a partner node.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A set of communications protocols
that support peer-to-peer connectivity functions
for both local and wide area networks. TCP/IP
can be used for client/server links between the
Client daemon and, for example, CICS for OS/2,
CICS for Windows NT.
type 2.0 node. An SNA node that attaches to a
subarea network as a peripheral node and
provides full 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.
U
URL. (Uniform Resource Locator.) 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.
user session. Any APPC session other than a
SNASVCMG session.

V
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.
W
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.
Glossary
Glossary 255

Glossary
256 CICS Transaction Gateway: UNIX Administration

Index
Special characters
x
CICSCLI.BIN 195, 197, 198
CICSCLI.LOG 69
CICSCLI.TRC 195
A
accessibility 241
Acrobat 26, 235
adapters 230
administration 135
Adobe 26, 235
advanced program-to-program communication
(APPC) 27, 42
Anynet domain name suffix configuration setting 76
APAR (authorized program analysis report)
authorization 215
closing 216
documentation needed 213
process 215
submitting 215
API (Application Programming Interface) 3
APPC (advanced program-to-program
communication) 27, 42
application development tools 25, 234
Application Programming Interface (API) 3
application servers 25, 233
application tracing 186
Applid configuration setting 66
asymmetric keys 7
authentication 10
Authorized Hosts configuration setting 64
B
beans, Java 14
binary trace formatter 197
BMS Map Conversion Utility 170, 181
books 237
CICS Transaction Gateway 237
browsers 23, 231
C
CA (certification authority) 8
CCLLOG.HLP 194
CCLMSG.HLP 194
CCLSNWTP.EXE 205
certification authority (CA) 8
cfwk.zip 191
CICS Gateway for Java 219
CICS gateway for Lotus Notes; 223
CICS resource adapters 81
CICS server problem determination 209
CICS server PTF requirements 26
CICS servers 24, 232
CICS servers, communicating with 37
CICS Transaction Gateway
CICS gateway for Lotus Notes; 223
hardware requirements 22
local 92
migration 217, 218
problem determination 183
starting CICS Transaction Gateway with preset
options 132
starting Gateway with user-specified options 132
startup options 132
stopping 134
cicscli command 139
CICSCLI environment variable 50, 218
CICSCLI.LOG 194
CICSCOL environment variable 90
cicseci.rar 81
cicsepi.rar 81
cicsftrc utility 197
cicsjava script 92
CICSKEY environment variable 88
cicsprnt command 157
cicsterm command 151
CLASSPATH 48, 224
CLASSPATH environment variable 114, 191, 192
CLASSPATH setting 48
client control 5
Client daemon
trace analysis 201
Client daemon tracing 196
Client daemon, restarting 141
Client daemon, starting 140
Client daemon, stopping 140, 141
client security 143
client trace file 201
Client trace file configuration setting 80
client tracing 142
security considerations 142
client/server connections 28
ClientSecurity 82, 84
Codepage identifier override configuration setting 68
codepage problems 189
color mapping file 90, 152
© Copyright IBM Corp. 1996, 2002 257

commands
cicscli 139
cicsprnt 157
cicsterm 151
Common Client Interface (CCI) 16
Common Object Request Broker (CORBA)
standard 19
Communicating with CICS servers 37
communication
problems 209
communication protocols 25, 233
APPC 27
TCP/IP 27
Communications server 211
compilers 25, 234
configuration
CLASSPATH 48
configuration file 49
configuration tool 49
Gateway.properties file 49
programming environment 48
configuration conversion tool 217
configuration file 49
referencing 50
renaming 87
configuration file, referencing 149
configuration settings
Anynet domain name suffix 76
Applid 66
Authorized Hosts 64
Client trace file 80
Codepage identifier override 68
Connection timeout 72
Connection timeout (ms) 58
Description 70
Display TCP/IP hostnames 55
Drop working connections 58
Enable protocol handler 57
Enable reading input from console 54
Fully qualified CP name or template 75
Gateway trace file 79
Gateway trace wrap size 80
Handler wakeup timeout (ms) 57
Hostname or IP address 72
Idle timeout (ms) 58
Initial number of Connection Manager threads 53
Initial number of Worker threads 54
Initial transaction 71
IP address mask for CP name (optional) 75
IP address mask for LU name template
(optional) 74
Java clients obtaining generic ECI replies 55
KeyRing or Keystore name 61
KeyRing or Keystore password 61
Local LU name 73
258 CICS Transaction Gateway: UNIX Administration
configuration settings (continued)
Local LU name or template 74
Log client connections and disconnections 56
Log file 69
Max dedicated connections 64
Maximum buffer size 67
Maximum Client wrap size 80
Maximum logical SNA sessions 76
Maximum number of Connection Manager
threads 54
Maximum number of Worker threads 54
Maximum requests 67
Maximum servers 67
Maximum SNA RU size 77
Mode name 73, 75
Model terminal definition 71
Partner LU name 73, 74
Ping time frequency (ms) 58
Port 57, 72
Print command 68
Print file 68
Remote node inactivity poll interval 76
Require clients to use security classes 59
Send TCP/IP Keepalive packets 72
Server name 70
Server retry interval 69
SNA pacing size 77
SO_LINGER setting 58
Terminal exit 67
Timeout for in-progress requests to complete
(ms) 56
Trace 78
Trace settings 195
Use client authentication 60
Use LU alias names 72
Use upper case security 71
Validate message qualifiers 55
Validate Units of Work 55
Worker thread available timeout (ms) 56
configuration tool 49
configuration tool help 243
connecting to CICS servers 140, 145
Connection timeout (ms) configuration setting 58
Connection timeout configuration setting 72
ConnectionURL 82, 83
console messages, disabling the display of 144
console messages, enabling the display of 144
CORBA (Common Object Request Broker) standard 19
Corrective Service Diskette (CSD) 216
CRSR transaction 42
CSD (Corrective Service Diskette) 216
CTG_JNI_TRACE 79, 187
ctgclient.jar 192
ctgconv, conversion tool 218
ctgikey 94, 105

ctgsamples.jar 224
ctgserver.jar 192
ctgstart command 132
customizing
keyboard 88
screen colors 90
D
Data conversion 44
dbx 207
defining 3270 printer terminal emulator
characteristics 157
defining 3270 terminal emulator characteristics 152
Description configuration setting 70
development tools 25, 234
DeviceType 85
diagnosing common problems
Client daemon 203
codepage problems 189
Gateway daemon 188
if a process locks 189
Java exceptions 192
Java security exceptions 192
java.lang.OutOfMemory exception 193
SSL exceptions 190
diagnostic tools
APING 211
digital certificates 8, 10
externally signed 95, 105
maintaining 94, 105
self-signed 100, 110
digital signatures 8
disability 241
disabling the display of console messages 144
disabling the display of messages 144
disk space required 230
DISPLAY environment variable 35
Display TCP/IP hostnames configuration setting 55
displaying command syntax 145
distinguished name (DN) 8
DN (distinguished name) 8
documentation 237
documenting problems 213
Drop working connections configuration setting 58
dynamic name generation (TCP62) 75
E
ECI (External Call Interface) 1, 3, 4
ECI resource adapter 82
Enable protocol handler configuration setting 57
Enable reading input from console configuration
setting 54
enabling the display of console messages 144
Encoding 85
encryption 7, 10
Enterprise Information Systems (EIS) 15
environment variables 87
CICSCLI 50, 218
CICSCOL 90
CICSKEY 88
CLASSPATH 48, 114, 191
CTG_JNI_TRACE 79, 187
JAVA_HOME 94, 105
LD_LIBRARY_PATH 92
PATH 92
SHLIB_PATH 92
EPI (External Presentation Interface) 1, 3, 4
EPI resource adapter 83
EPIBasicScreenHandler 224
EPIMonitor 224
EPIScreenButtons 224
error log 211
CICSCLI.LOG 194
client error log 194
server error log 209
ESI (External Security Interface) 1, 3, 4
Euro support 68
EXEC CICS RETURN TRANSID IMMEDIATE
command 153, 158
External Call Interface (ECI) 1, 3, 4
External Presentation Interface (EPI) 1, 3, 4
External Security Interface (ESI) 1, 3, 4
externally-signed certificates 9
F
firewalls 14
free memory 67
Fully qualified CP name or template configuration
setting 75
G
Gateway daemon tracing 185
Gateway trace file configuration setting 79
Gateway trace wrap size 80
Gateway.properties file 49
generic ECI replies
Configuration 55
GhostView 26, 235
glossary of terms and abbreviations 245
H
Handler wakeup timeout (ms) configuration
setting 57
hangs 189, 206
hardware requirements 22
help 243
Hostname or IP address configuration setting 72
HTTP (Hypertext Transfer Protocol) 2
HTTP over SSL (HTTPS) 2
HTTPS 12
HTTPS (HTTP over SSL) 2
Index 259

Hypertext Transfer Protocol (HTTP) 2
I
IBM Communications Server 211
Idle timeout (ms) configuration setting 58
IIOP (Internet InterOrb Protocol) 19
iKeyMan 94, 105
distributing to client workstations 94
inactivity poll interval 41
Initial number of Connection Manager threads
configuration setting 53
Initial number of Worker threads configuration
setting 54
initial transaction 152, 157
Initial transaction configuration setting 71
initialization files
CICSCOL.INI 90
CICSKEY.INI 88
install_path x
installation
CICS Transaction Gateway 31
path x
installation path x
InstallTimeout 85
internal client communication in UNIX systems 44
Internet InterOrb Protocol (IIOP) 19
IP address mask for CP name (optional) configuration
setting 75
IP address mask for LU name template (optional)
configuration setting 74
J
J2EE
resource adapter files 81
resource adapters 3
Java
applet 13
application 13
beans 14
classes 3
firewall 14
Java language 12
samples 224
servlet 13
Java development kit 24, 232
Java exceptions 192
Java Secure Socket Extension (JSSE) 24, 232
Java security exceptions 192
JAVA_HOME environment variable 94, 105
java.lang.OutOfMemory exception 193
JDK levels 24, 232
JNI tracing 78, 135, 186
JSSE 9, 11, 24, 104, 105, 232
installation 104
migration from SSLight 104
260 CICS Transaction Gateway: UNIX Administration
K
KeepAlive packets 41
keyboard 241
keyboard mapping file 88, 152
KeyRing or Keystore name configuration setting 61
KeyRing or Keystore password configuration
setting 61
KeyRingClass 83, 85
KeyRingPassword 83, 85
KeyRings 9, 94
KeyStores 9, 105
L
LD_LIBRARY_PATH 92
license file 32
listing connected servers 144
local CICS Transaction Gateway 92
local gateway connection 13
Local LU name configuration setting 73
Local LU name or template configuration setting 74
locks 189
Log file configuration setting 69
logical unit (LU) 42
LogonLogoffClass 85
LU6.2 27
M
mapping files
renaming 87
Max dedicated connections configuration setting 64
Maximum buffer size configuration setting 67
Maximum Client wrap size configuration setting 80
Maximum logical SNA sessions configuration
setting 76
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 67
Maximum SNA RU size configuration setting 77
memory leak 193
memory requirements 67
message queues 44
messages 184, 194
messages, disabling the display of 144
migrating from CICS Gateway for Java 219
Migrating from CICS Transaction Gateway Version
4 218
migration
CICS Gateway for Java 219
CICS Universal Client Version 3.0 219
migration issues 217, 218
mode definitions, APPC 42
Mode name configuration setting 73, 75

Model terminal definition configuration setting 71
N
national language support 33
network gateway connection 13
network security
authentication 10
certification authority (CA) 8
concepts 6
ctgikey 94, 105
digital certificates 8, 10
externally signed 95, 105
maintaining 94, 105
self-signed 100, 110
digital signatures 8
distinguished name (DN) 8
encryption 7, 10
externally-signed certificates 9
HTTPS 12, 114
iKeyMan 94, 105
distributing to client workstations 94
JSSE 9, 11, 104, 105
installation 104
migration from SSLight 104
KeyRings 9, 94
keys 7
KeyStores 9, 105
migrating old self-signed certificates 104, 114
security exits 12
self-signed certificates 9
signer certificate 8
SSL 10, 114
SSL handshaking 10
SSLight 11, 94
System SSL 11
trusted root key 8
X.509 protocol 8, 10
O
object request broker (ORB) 19
online help, for end user messages, 194
onlne help, for trace and log messages 194
operating systems 23, 230
operation
starting the Gateway 132
stopping the Gateway 134
options
cicscli command 145
cicsprnt command 159
cicsterm command 154
ORB (object request broker) 19
P
Partner LU name configuration setting 73, 74
Password 82, 84
password expiry management (PEM) 4, 119
PATH 92
PEM (password expiry management) 4, 119
performance
assessing 125
CICS Transaction Gateway configuration 126
Java considerations 128
monitoring 130
other system factors 128
tracing 129
Ping time frequency (ms) configuration setting 58
planning 21
PMR (Problem Management Record) 212
Port configuration setting 57, 72
PortNumber 82, 84
Print command configuration setting 68
Print file configuration setting 68
print file, processing 152, 157
print terminal emulator, starting 157
printer support 5
printer terminal emulator characteristics, defining 157
problem determination 183
application tracing 186
diagnosing common problems
Gateway daemon 188
Gateway daemon tracing 185
JNI tracing 186
messages 184, 194
preliminary checks 183
servlet tracing and logging in WebSphere 187
tracing
Client daemon 195
Gateway daemon 185
Problem Management Record (PMR) 212
problem reporting
documenting problems 213
information needed 214
support organization 212
problems, communication 209
process locks 189
program support 212
protocols
HTML 16
HTTP 2
HTTPS 2
SSL 2, 10
TCP/IP 2
PTF (Program Temporary Fix) 216
public key encryption 7
publications, CICS Transaction Gateway 237
R
railroad diagrams x
re-authentication support 83, 86
README file 21
ReadTimeout 85
Index 261

Remote Method Invocation (RMI) 19
Remote node inactivity poll interval 41
Remote node inactivity poll interval configuration
setting 76
Require clients to use security classes configuration
setting 59
requirements, hardware 22
resource adapter files 81
resource adapters 81
resource adapters, J2EE 3
Restarting the Client daemon 141
restrictions, using CICS servers 28
RETAIN database 212
RETAIN problem management system
APARs 215
Problem Management Record 212
RMI (Remote Method Invocation) 19
S
samples text file 171
samples, Java 224
Samples.txt 171, 172
screen readers 234
Secure Sockets Layer (SSL) 2, 10
security 71
External Security Interface (ESI) 4
password expiry management (PEM) 4
security exits 12
self-signed certificates 9
Send TCP/IP Keepalive packets configuration
setting 72
Server name configuration setting 70
Server retry interval configuration setting 69
ServerName 82, 84
servers
application 25, 233
CICS 24, 232
web 25, 233
servers, listing 144
ServerSecurity 83, 84
servlet tracing and logging in WebSphere 187
servlets 13
SHLIB_PATH 92
shortcut keys 241
signer certificate 8
signon capable terminals 26
SignonType 85
SMIT 207, 211
smitty 207, 211
SNA 25, 233
checking configuration 211
configuring 42
SNA (Systems Network Architecture) 27
SNA pacing size configuration setting 77
sna.err 211
262 CICS Transaction Gateway: UNIX Administration
SO_LINGER setting configuration setting 58
SSL (Secure Sockets Layer) 2, 10
SSL exceptions 190
SSL handshaking 10
SSLight 11, 94
starting a 3270 print terminal emulator 157
starting a 3270 terminal emulator 152
starting CICS Transaction Gateway 132
Starting the Client daemon 140
stopping a terminal emulator 153
Stopping the Client daemon 140, 141
stopping the Gateway 134
support organization
program support 212
sending documentation to 215
symmetric keys 7
syntax notation x
System SSL 11
Systems Network Architecture (SNA) 27
T
TCP/IP (Transmission Control Protocol/Internet
Protocol) 2, 25, 27, 37, 234
TCP/IP communication problems 204
TCP62 25, 234
communication problems 205
port number 76
TCP62 protocol 38
TCP62 support 29
TCPAdmin protocol settings 64
Telnet 23, 231
terminal emulation 4
terminal emulator characteristics, defining 152
terminal emulator, starting 152
terminal emulator, stopping 153
Terminal exit configuration setting 67
Terminal Servlet 4
the system locks up 206
thread limits 17
timeout 85
Timeout for in-progress requests to complete (ms)
configuration setting 56
tools
application development 25, 234
other 26, 235
TPNName 82
Trace configuration setting 78
Trace settings, configuration tool 195
TraceLevel 83, 86
tracing 86
Client daemon 195
dynamic 135
Gateway daemon 135, 185
JNI 135
levels 86

tracing (continued)
performance considerations 186
query current trace settings 135
tracing, JNI 186
TranName 82
transaction programs (TP), APPC 42
transaction support 83, 86
transmission control protocol/internet protocol
(TCP/IP) 27
Transmission Control Protocol/Internet Protocol
(TCP/IP) 2, 27, 37
traps 206
troubleshooting
hangs 206
starting clients and terminals 204
traps 206
trusted root key 8
U
uninstalling CICS Transaction Gateway 35
upgrading 218
Use client authentication configuration setting 60
Use LU alias names configuration setting 72
Use upper case security configuration setting 71
Userid 82, 84
V
Validate message qualifiers 55
Validate Units of Work 55
variables, environment 87
VTAM
buffer trace 210
W
web browsers 23, 231
web servers 25, 233
Web servers 15
Worker thread available timeout (ms) configuration
setting 56
X
X-Windows 35
X.509 protocol 8, 10
XAResource 83
Index 263

264 CICS Transaction Gateway: UNIX Administration

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.
© Copyright IBM Corp. 1996, 2002 265

Trademarks
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 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
CICS eNetwork
IBM MQSeries
MVS MVS/ESA
OS/390 OS/400
RETAIN TXSeries
VisualAge VSE/ESA
VTAM WebSphere
266 CICS Transaction Gateway: UNIX Administration

Lotus Domino, Lotus Notes, and Domino Go Webserver are trademarks of
Lotus Development Corporation.
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 in the United States and other countries
licensed exclusively through X/Open Company Limited.
Other company, product or service names may be trademarks or service
marks of others.
Notices 267

268 CICS Transaction Gateway: UNIX 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, 2002 269

����
Program Number: 5724-D12
Printed in U.S.A.
SC34-6139-00

Spine information:
��� CICS Transaction Gateway UNIX Administration Version 5.0

CICS Transaction Gateway
z/OS Administration
Version 5.0
���
SC34-6191-00

CICS Transaction Gateway
z/OS Administration
Version 5.0
���
SC34-6191-00

Note!
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page 191.
First Edition (July 2002)
This edition applies to Version 5.0 of CICS ® Transaction Gateway for z/OS ® program number 5724-D12. It will also
apply to all subsequent versions, releases, and modifications until otherwise indicated in new editions.
This edition replaces SC34-5935. Vertical lines at the left side of the page indicate material that is new to this edition.
© Copyright International Business Machines Corporation 1996, 2002. 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
Conventions and terminology used in this
book . . . . . . . . . . . . . . viii
Installation path . . . . . . . . . . x
Programming language specific . . . . . x
Operating system specific . . . . . . . x
Syntax notation . . . . . . . . . . x
Summary of changes . . . . . . . . xiii
Chapter 1. Overview . . . . . . . . . 1
What CICS Transaction Gateway provides . . 3
A Gateway daemon. . . . . . . . . 3
The Gateway classes . . . . . . . . 3
J2EE resource adapters . . . . . . . . 3
The external access interfaces (ECI, EXCI) . 3
Network security. . . . . . . . . . . 4
Encryption . . . . . . . . . . . . 5
Digital signatures and digital certificates . . 5
Obtaining a digital certificate. . . . . . 6
KeyRings and KeyStores . . . . . . . 7
Authentication using SSL . . . . . . . 8
HTTPS . . . . . . . . . . . . . 10
Security exits. . . . . . . . . . . 10
Java technology . . . . . . . . . . . 10
The Java language . . . . . . . . . 11
Java applets . . . . . . . . . . . 11
Java servlets . . . . . . . . . . . 11
Java applications . . . . . . . . . 12
Firewalls . . . . . . . . . . . . 12
Web servers . . . . . . . . . . . 13
The J2EE resource adapters . . . . . . . 13
How CICS Transaction Gateway accesses
CICS . . . . . . . . . . . . . . 14
The CICS Transaction Gateway: threading
model . . . . . . . . . . . . . . 14 15
Chapter 2. Planning your installation . . . 19
Disk space requirements . . . . . . . . 19
Software requirements . . . . . . . . 20
Operating systems . . . . . . . . . 20
Web browsers . . . . . . . . . . 20
JDK levels. . . . . . . . . . . . 21
JSSE. . . . . . . . . . . . . . 21
CICS Servers. . . . . . . . . . . 21
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Web servers . . . . . . . . . . . 21
Application servers . . . . . . . . 21
Checking the z/OS shell environment . . . 22
National Language Support . . . . . . . 22
Coexistence with other products . . . . . 22
Migrating from CICS Gateway for Java (MVS) 23
Migrating from CICS Transaction Gateway for
OS/390 Version 3 . . . . . . . . . . 24
Migrating from CICS Transaction Gateway
Version 4 . . . . . . . . . . . . . 24
Chapter 3. Installation . . . . . . . . 25
Installation: overview . . . . . . . . . 26
OMVS features . . . . . . . . . . 26
Installation: detail . . . . . . . . . . 27
Step 1: Gather information and obtain the
necessary permissions. . . . . . . . 27
Step 2: (Optional) Make a safe home for
the CICS Transaction Gateway . . . . . 28
Step 3: Upload, unpack and install . . . 31
Installing into a locale other than 1047 (U.S.
English) . . . . . . . . . . . . . 32
Changing the code page after installation 33
Directory structure . . . . . . . . . . 33
Uninstalling the CICS Transaction Gateway
for z/OS . . . . . . . . . . . . . 34
Using X-Windows from a remote system . . 34
Extracting and installing the PDF library . . 35
Service and updates . . . . . . . . . 36
Chapter 4. Configuring the CICS
Transaction Server for z/OS . . . . . . 37
CICS server connection definition . . . . . 37
CICS server sessions definition. . . . . . 40
Open interregion communication . . . . . 42
EXCI user-replaceable module DFHXCURM 42
Chapter 5. Configuring the CICS
Transaction Gateway . . . . . . . . 43
Editing the sample configuration files . . . 43
General Gateway settings in CTG.INI . . . 45
Protocol settings . . . . . . . . . 45
Summary of environment variables . . . 46
Setting environment variables . . . . . . 47
The environment variables . . . . . . 48
© Copyright IBM Corp. 1996, 2002 iii

|
|
|
|
|
|
|
|
|
|
|
|
Customizing EXCI options . . . . . . 50
Using the configuration tool . . . . . . 52
Running the configuration tool on a
different operating system . . . . . . 53
The configuration tool interface . . . . 53
Configuring CICS Transaction Gateway
settings . . . . . . . . . . . . 56
Configuring CICS Transaction Gateway for
use with RACF ®
. . . . . . . . . . 65
Problems . . . . . . . . . . . . 67
J2EE setup and configuration . . . . . . 67
Deploying CICS resource adapters . . . 68
Tracing. . . . . . . . . . . . . 71
Other configuration tasks: . . . . . . . 73
Increasing the CPUTIME timeout when the
volume of traffic is high . . . . . . . . 73
Chapter 6. Network Security . . . . . . 75
Determining your use of SSLight or JSSE for
the SSL and HTTPS protocols . . . . . . 76
SSLight . . . . . . . . . . . . . 76
Conflict with JSSE . . . . . . . . . 76
Maintaining your digital certificates for
SSLight . . . . . . . . . . . . 76
Using externally signed certificates under
SSLight . . . . . . . . . . . . 77
Using self-signed certificates under SSLight 82
Java Secure Socket Extension (JSSE) . . . . 86
Migration from SSLight . . . . . . . 86
Installation . . . . . . . . . . . 86
Maintaining your digital certificates for
JSSE. . . . . . . . . . . . . . 87
Using externally signed certificates under
JSSE. . . . . . . . . . . . . . 87
Using self-signed certificates under JSSE 91
System SSL . . . . . . . . . . . . 95
Maintaining your digital certificates for
System SSL . . . . . . . . . . . 95
Using externally signed certificates under
System SSL . . . . . . . . . . . 96
Using self-signed certificates under
System SSL . . . . . . . . . . . 101
Mapping client certificates to RACF userids 105
Associate a client certificate with a RACF
userid. . . . . . . . . . . . . 105
Map a certificate to its associated RACF
userid. . . . . . . . . . . . . 106
Configuring CICS Transaction Gateway for
SSL and HTTPS . . . . . . . . . . 107
SSL and HTTPS configuration settings 107
iv CICS Transaction Gateway: z/OS Administration
|
|
|
|
|
|
|
|
|
|
|
|
Specifying a client KeyRing or KeyStore 107
Using the SSL and HTTPS protocols . . 108
Other security considerations . . . . . . 108
Chapter 7. Performance . . . . . . . 109
Assessing system performance . . . . . 109
CICS Transaction Gateway configuration . . 110
Java considerations . . . . . . . . . 112
Other system factors . . . . . . . . . 113
Tracing . . . . . . . . . . . . . 114
Performance monitoring tools . . . . . . 114
Chapter 8. Operation . . . . . . . . 117
Testing your configuration . . . . . . . 117
Starting the CICS Transaction Gateway. . . 117
Starting from a command line. . . . . 117
Automatic restart management . . . . 119
Starting with JCL . . . . . . . . . 121
Starting multiple CICS Transaction
Gateways . . . . . . . . . . . 124
Stopping the CICS Transaction Gateway . . 127
Administering your system . . . . . . 128
Setting the Gateway trace . . . . . . 128
Setting the JNI trace . . . . . . . . 128
Querying trace settings . . . . . . . 128
Parameters . . . . . . . . . . . 129
Chapter 9. Problem determination . . . 131
Preliminary checks . . . . . . . . . 131
What to do next . . . . . . . . . . 131
Messages . . . . . . . . . . . . 132
Sources of information . . . . . . . . 132
Tracing . . . . . . . . . . . . . 133
Gateway tracing . . . . . . . . . 134
Application tracing . . . . . . . . 135
JNI tracing . . . . . . . . . . . 135
J2EE Tracing . . . . . . . . . . 136
EXCI trace . . . . . . . . . . . 137
Diagnosing common problems . . . . . 139
Installation . . . . . . . . . . . 139
The configuration tool . . . . . . . 139
EDC5111I PERMISSION DENIED
message . . . . . . . . . . . . 139
CEE3250C ABEND S806 message . . . 140
Multiple Address Spaces . . . . . . 140
Automatic Restart Manager (ARM)
problems. . . . . . . . . . . . 140
Conflicts with default ports . . . . . 141
EXCI pipe limitations . . . . . . . 141
Java exceptions . . . . . . . . . 142

|
|
java.lang.OutOfMemory exception . . . 143
Authorization failure using servlets with
WebSphere . . . . . . . . . . . 145
If a process locks . . . . . . . . . 145
SSL problems . . . . . . . . . . 145
Shortage of resources on the CICS server 147
ECI_ERR_SECURITY_ERROR return code 147
ECI_ERR_SYSTEM_ERROR return code 148
Dirty address space problems . . . . . 148
Program support . . . . . . . . . . 149
Reporting problems . . . . . . . . 149
Documenting problems . . . . . . . 150
Locating and compiling information . . 151
Submitting the documentation . . . . 152
APARs and fixes . . . . . . . . . 152
Appendix A. Hardware and software. . . 155
Hardware requirements. . . . . . . . 155
Supported software . . . . . . . . . 156
Operating systems . . . . . . . . 156
Web browsers . . . . . . . . . . 157
Telnet clients . . . . . . . . . . 157
JDK levels . . . . . . . . . . . 158
JSSE . . . . . . . . . . . . . 158
CICS Servers . . . . . . . . . . 158
Web servers. . . . . . . . . . . 159
Application servers . . . . . . . . 159
SNA communications . . . . . . . 159
TCP/IP communications . . . . . . 160
TCP62 communications . . . . . . . 160
Compilers and application development
tools . . . . . . . . . . . . . 160
Screen readers . . . . . . . . . . 160
Other tools . . . . . . . . . . . 161
GPL licence and copyright issues on
Linux . . . . . . . . . . . . . 161
|
|
|
|
|
|
|
|
|
|
|
Appendix B. Supported code pages . . . 163
The product library and related literature 165
CICS Transaction Gateway books . . . . 165
Sample configuration documents. . . . . 166
Redbooks . . . . . . . . . . . . 167
Other Useful Books . . . . . . . . . 167
CICS Transaction Server publications . . 167
APPC-related publications . . . . . . 168
TCP62–related publications . . . . . 168
Obtaining books from IBM. . . . . . . 168
Accessibility . . . . . . . . . . . 169
Documentation . . . . . . . . . . 169
iKeyMan. . . . . . . . . . . . . 169
Samples . . . . . . . . . . . . . 169
Configuration tool accessibility . . . . . 169
Components . . . . . . . . . . 169
Keys . . . . . . . . . . . . . 169
Customizing colors and fonts . . . . . 171
Using help . . . . . . . . . . . 171
Task Guide . . . . . . . . . . . 172
Glossary . . . . . . . . . . . . 173
Index . . . . . . . . . . . . . 185
Notices . . . . . . . . . . . . . 191
Trademarks . . . . . . . . . . . . 192
Sending your comments to IBM . . . . 195
Contents v

vi CICS Transaction Gateway: z/OS Administration

About this book
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.
Summary of changes Read this for information on functional changes made in this
version of CICS Transaction Gateway.
Chapter 1, “Overview” Read this for an overview of CICS Transaction Gateway and
the functions it provides.
Chapter 2, “Planning
your installation”
Chapter 3,
“Installation”
Chapter 4,
“Configuring the CICS
Transaction Server for
z/OS”
Chapter 5,
“Configuring the CICS
Transaction Gateway”
Chapter 6, “Network
Security”
Chapter 7,
“Performance”
Chapter 8,
“Operation”
Chapter 9, “Problem
determination”
Migrating from CICS
Gateway for Java
(MVS)Migrating from
CICS Transaction
Gateway for OS/390
Version 3
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 configure EXCI
connections, to allow CICS Transaction Gateway to connect
to a CICS region.
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 network security protocols SSL and
HTTPS.
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 Gateway
daemon.
Read this for information on problem determination and
problem solving.
Read these if you are currently using an earlier version of
CICS Transaction Gateway.
© Copyright IBM Corp. 1996, 2002 vii

The product library
and related literature
Read this for information on the CICS Transaction Gateway
product library and related literature, and the various forms
in which it is available.
Accessibility Read this for information on the accessibility features of CICS
Transaction Gateway.
Notices Read this for important information on the availability of
IBM products and service in different countries, and also on
issues concerning patents, licenses, and trademarks.
Sending your
comments to IBM
Read this for information on how to send your comments to
IBM.
Conventions and terminology used in this book
A number of parts, both internal and external to the CICS Transaction
Gateway, are used when creating a business solution using the product.
Figure 1 on page ix shows some of the possible scenarios you will encounter,
and the terminology used in each case.
viii CICS Transaction Gateway: z/OS Administration

Distributed platforms running in remote mode
Java client
application
z/OS running in local mode
Java client
application
Gateway
classes
Gateway
classes
CICS
server
Gateway
daemon
Distributed platforms running in local mode
Java client
application
Gateway
classes
Client
daemon
Distributed platforms running non-Java applications
Client
application
Client
daemon
z/OS running in remote mode
Java client
application
Gateway
classes
CICS
server
Gateway
daemon
Client
daemon
CICS
server
CICS
server
Figure 1. CICS Transaction Gateway uses, with their associated terminology
CICS
server
The following explains the terms used in Figure 1:
Gateway daemon
Used only in remote mode, the Gateway daemon listens on protocols
defined in CTG.INI for gateway requests from remote Java client
applications. It issues these requests to the Client daemon on
distributed platforms, and directly to CICS over the EXCI on z/OS.
The Gateway daemon runs the protocol listener threads, the worker
threads and the connection manager threads. It uses the GATEWAY
section of CTG.INI (and on z/OS the ctgenvvar script) for its
configuration.
Client daemon
The Client daemon (process cclclnt) exists only on distributed
platforms. 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.
About this book ix

Gateway classes
The interface for Java Client applications to connect to the Gateway
daemon. The Gateway classes, which are supplied with the CICS
Transaction Gateway, must be in the classpath for Java Client
applications to run.
Client application
A user application, written in a supported programming language
other than Java, that communicates directly with the Client daemon.
Java Client application
A Java application, servlet or applet that communicates with the
Gateway classes.
Installation path
The term is used in file paths to represent the directory where
you installed the product. The default installation locations for each operating
system are shown in Table 1:
Table 1. Default CICS Transaction Gateway installation locations
Operating System Default installation location
Windows ®
c:\Program Files\IBM\IBM CICS Transaction Gateway
AIX ®
/usr/lpp/ctg
Linux, HP-UX, Solaris /opt/ctg
z/OS A ctg subdirectory of the directory from which the
installation was run. For example, if the CICS
Transaction Gateway was installed by the command
ctginstall in the /usr/lpp directory, the
is /usr/lpp/ctg
Programming language specific
The term C refers to both the C and C++ programming languages.
Operating system specific
Unless otherwise specified, the term Windows refers to Windows NT ® ,
Windows 2000, and Windows XP.
The term Windows 2000 Terminal Server means a server with the Terminal
Services feature installed.
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.
Syntax notation
The syntax of commands is shown in a standard way. This syntax, commonly
known as railroad syntax, is described in Table 2 on page xi. You interpret the
syntax by following the arrows from left to right, and from top to bottom,
x CICS Transaction Gateway: z/OS Administration

along the main path line.
Table 2. Command syntax conventions
Symbol Meaning
Required items appear on the main path line.
►► AB ►◄
►► A
B
C
►►
►►
►►
A B
A
B
C
A
B
C
►► ▼ A
►► ▼
A
B
C
B
►◄
►◄
►◄
►◄
►◄
►◄
Punctuation and uppercase
characters
Lowercase characters appearing
like this
If there is more than one required item to choose
from, the items are stacked vertically. This is a set of
alternatives—one of which you must specify.
Optional items appear below the main path line.
If there is more than one optional item to choose
from, the items are stacked vertically below the
main path line. This is a set of alternatives—one of
which you may specify.
If one item in a set of alternatives is the default, this
item appears above the main path line and all other
items are stacked vertically below the line.
An arrow returning to the left above items on the
main path line means that the items can be repeated.
Such items may be either required or optional.
An arrow returning to the left above a set of items
means that more than one item can be selected or
that a single item can be repeated.
Note: For CICS, unless otherwise stated, this
representation means only that more than one item
can be selected.
Code exactly as shown.
Code your own text, as appropriate. For example,
with FILE(name) you must specify FILE and ()
unchanged, but are free to specify any valid text
string for the name of your file.
About this book xi

xii CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Summary of changes
The following functional changes have been made for CICS Transaction
Gateway Version 5.0:
v The CICS Transaction Gateway supports z/OS Automatic Restart Manager
(ARM); see “Automatic restart management” on page 119.
v A systems administration function allows you to set options for Gateway
and JNI traces, to start and stop these traces, and to query trace settings;
see “Administering your system” on page 128. Using the CTG_JNI_TRACE
environment variable to enable JNI tracing is supported only for migration
purposes.
v The way that CICS Transaction Gateway writes log messages has changed:
– Each message entry begins with the current date in the format
month/day/year.
– CICS Transaction Gateway writes error and warning messages to
standard error (stderr), and information messages to standard output
(stdout); see “Messages” on page 132.
– A new gateway configuration setting, Log client connections and
disconnections, controls whether CICS Transaction Gateway writes a
message each time that a client application program connects to, or
disconnects from, the Gateway daemon. See “Log client connections and
disconnections” on page 58.
v Java Secure Socket Extension (JSSE) is supported.
This gives 128 bit encryption capability and is IBM’s recommended solution
for SSL. For compatibility with previous versions of CICS Transaction
Gateway, this version supports both JSSE and SSLight. However, support
for SSLight might be removed in a future release.
This edition replaces SC34-5935.
Vertical lines at the left side of the page indicate material that is new to this
edition.
© Copyright IBM Corp. 1996, 2002 xiii

xiv CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
Chapter 1. Overview
IBM CICS Transaction Gateway provides secure, easy access from Web
browsers and network computers to CICS applications, using standard
Internet protocols in a range of configurations. It is a robust and scalable
complement to a Web 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. 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
the Windows and UNIX ® operating systems, CICS Transaction Gateway can
access many different types of CICS server. On z/OS CICS Transaction
Gateway can access only CICS Transaction Server for z/OS. See “Software
requirements” on page 20 for information on supported operating systems and
CICS servers.
On the Windows and UNIX operating systems, 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, EXCI)” on page 3). On z/OS, CICS
Transaction Gateway can route only ECI requests, and has no Client daemon.
On z/OS, the CICS Transaction Gateway actually uses the CICS External Call
Interface (EXCI) to pass requests to CICS (see “CICS External Call Interface
(EXCI)” on page 3). However, to a Java applet or application, these appear to
be ECI requests.
© Copyright IBM Corp. 1996, 2002 1

Overview
Network
computer
Figure 2 shows how a web client can access CICS programs and data. Note
that the CICS Transaction Gateway is shown as installed on a Web server
machine. This is necessary only if you are using the CICS Transaction
Gateway with Java applets or servlets.
HTTP
Web server
System SSL
HTTPS
Java-enabled
browser
HTTPS
SSL
CICS
Transaction
Gateway
Figure 2. CICS Transaction Gateway
TCPAdmin
System SSL
TCP
HTTP
Local
Local
Java application
Server machine
EXCl
CICS
server
Communication between CICS Transaction Gateway and the client application
uses the following protocols:
v Transmission control protocol/Internet protocol (TCP/IP) sockets
v Hypertext Transfer Protocol (HTTP)
v Secure Sockets Layer (SSL)
v HTTP over SSL (HTTPS)
TCP/IP sockets and SSL provide an efficient method of communication for
intranet applications. Where firewalls exist, HTTP, and its secure alternative
HTTPS, are effective communication protocols for internet applications. See
“Network security” on page 4.
2 CICS Transaction Gateway: z/OS Administration

CICS Transaction Gateway can manage many concurrent links to connected
Web browsers. The multithreaded architecture of the CICS Transaction
Gateway enables a single gateway to support multiple concurrently connected
users.
What CICS Transaction Gateway provides
Overview
A Gateway daemon
This communicates with CICS applications running on CICS servers through
EXCI.
The Gateway classes
This Java library includes classes that:
v provides an Application Programming Interface (API) for ECI
This allows communication between Java applications, or Java servlets, and
the Gateway daemon.
v allow client applications to communicate with transactions on a server
v allow your applications to use the SSL network security protocol
J2EE resource adapters
Use these to provide a J2EE-compliant interface to CICS for your applications.
The external access interfaces (ECI, EXCI)
The external access interfaces allow non-CICS applications to access and
update CICS resources by initiating CICS transactions, or by calling CICS
programs. When used in conjunction with the CICS communication facilities,
they enable 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.
These APIs are provided for both Java and non-Java programming languages.
External Call Interface (ECI)
The ECI enables a non-CICS client 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.
CICS External Call Interface (EXCI)
The external CICS interface (EXCI) is analogous to the ECI. It is an application
programming interface that enables a program running on z/OS, such as
CICS Transaction Gateway, to call a program running in a CICS region. The
programs can transfer data between each other using a communication area.
CICS Transaction Gateway supports Version 2 of the EXCI.
Chapter 1. Overview 3

What CICS Transaction Gateway provides
Network security
The EXCI allows a user to allocate and open sessions (or pipes) to a CICS
region, and to pass distributed program link (DPL) requests over them. The
multiregion operation (MRO) facility of CICS inter-region communication (IRC)
facility supports these requests, and each pipe maps onto one MRO session,
with a limit of 100 pipes per EXCI address space.
For more information on ECI, see CICS Transaction Gateway: Programming
Guide and CICS Transaction Gateway: Programming Reference.
For more information on EXCI, see CICS Transaction Server for OS/390 V1R3
CICS Intercommunication Guide.
CICS Transaction Gateway provides comprehensive support for secure
communication, which is critical to successful Internet operation. The secure
network protocols SSL and HTTPS allow your 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 75; the following sections summarize
the functions provided by SSL and HTTPS.
The characteristics of secure communication are:
Confidentiality
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.
Integrity
Messages are not altered during transmission.
Integrity guarantees that the message you sent reaches the recipient
intact. Encryption and digital signatures ensure integrity.
Accountability
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.
Authenticity
You know who you are talking to and you can trust that person.
4 CICS Transaction Gateway: z/OS Administration

Network security
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:
1. 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.
2. 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 8.
Digital signatures and digital certificates
A digital signature is a unique, mathematically computed, signature that
ensures accountability.
Chapter 1. Overview 5

Network security
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 certification 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 CA, or you can
6 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
Network security
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 certification authority
If you plan to conduct commercial business on the Internet, buy a server
certificate from a CA such as VeriSign or Thawte.
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 may choose to
allow access to only a carefully controlled group of key people within your
intranet.
Your key people should have browsers, such as Netscape Navigator, 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 75 for more information on
obtaining digital certificates.
KeyRings and KeyStores
Digital certificates, public keys, private keys, and trusted root keys are kept in
special types of file which the security protocols can use:
v SSLight, System SSL, and HTTPS use Java class files called KeyRings
v Java Secure Socket Extension (JSSE) uses files called KeyStores
For SSLight and JSSE: CICS Transaction Gateway uses KeyRings and
KeyStores to hold information about certificates and keys on both the SSL
server and SSL clients. See “SSLight” on page 76, and “Java Secure Socket
Extension (JSSE)” on page 86, for information on how to create these files. The
SSL and HTTPS protocols require access to these files to establish secure
connections. See “Configuring CICS Transaction Gateway for SSL and HTTPS”
on page 107 for information on how to provide this access.
For System SSL: CICS Transaction Gateway uses a key database file to hold
information about certificates and keys on the SSL server. See “System SSL”
on page 95, for information on how to create the key database file. The SSL
and HTTPS protocols require access to this key database file to establish
Chapter 1. Overview 7

Network security
secure connections. See “Configuring CICS Transaction Gateway for SSL and
HTTPS” on page 107, 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 9 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
8 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
Client Server
Client issues secure session request
(https.//someserver.org/somedata.html)
Server sends X.509 certificate containing server’s public key
Client authenticates certificate against list of known CA’s
(If CA is unknown browser can give user option to accept certificate at user’s risk)
Client generates random symmetric key and encrypts it using server’s public key
Client and server now both know the symmetric key
and encrypt end-user data using symmetric key for duration of session
Figure 3. SSL handshaking with server authentication
Network security
CICS Transaction Gateway supports the following implementations of SSL:
SSLight
An implementation of SSL that is written in pure Java.
This protocol is supported for compatibility with previous
versions of CICS Transaction Gateway. However, support for
SSLight might be removed in a future release.
JSSE
Another Java implementation, that provides support for 128
bit encryption.
IBM recommends that you use JSSE in preference to SSLight.
See “Migration from SSLight” on page 86, for more
information.
System SSL
Chapter 1. Overview 9

Network security
This implementation, which is written in native code, is
supported only for SSL servers on z/OS. It supports hardware
encryption technology available to the z/OS operating system.
Client side code always uses SSLight. However, IBM
recommends that you use System SSL on the server side, in
preference to SSLight, because it improves performance
significantly. The strongest level of cryptographic strength that
CICS Transaction Gateway supports is DES 56-bit. However,
on z/OS it is possible to import a VeriSign Step-Up Server
certificate that enables the SSLight client code, and other
export-strength SSL clients, to increase their cryptographic
strength dynamically to 128-bit.
HTTPS
HTTPS is a protocol that combines SSL and HTTP, and is used for handling
secure transactions. You specify https:// as an anchor in HTML documents
that link to documents protected by SSL. A client user can also open a URL by
specifying https:// to request an SSL-protected document.
Because HTTPS and HTTP are different protocols, and usually use different
ports (443 and 8080 respectively), you can run both SSL and non-SSL requests
at the same time. This allows you to provide information to all users using no
security, and specific information only to browsers which make secure
requests. This is how retail companies on the Internet allow users to look
through the merchandise without security, but then fill out order forms and
send their credit card numbers using security.
Security exits
CICS Transaction Gateway provides exits that enable the user to define
security operations such as public key encryption. They may also be used for
data compression. Some example source files are provided in this directory:
/samples/java/com/ibm/ctg/samples/security
Java technology
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 book.
This section discusses the Java language, including the types of program that
can be developed, and the security implications.
10 CICS Transaction Gateway: z/OS Administration

|
|
|
|
The Java language
Java is an interpreted object-oriented language, similar to C++. It can be used
to build programs that are independent of operating systems in both source
and object form. Its unique operational characteristics, which span Web
browsers as well as Web servers, enable new and powerful functions in
Internet applications.
To achieve operating system independence, the Java language allows no
operations that are dependent on specific operating system. Also, it excludes
some C++ functions such as a preprocessor, operator overloading, multiple
inheritances, and pointers. All Java programming is encapsulated within
classes, and the Java Development Kit (JDK) includes special classes that are
critical to assuring operating system independence, including GUI functions,
input/output functions, and network communications.
The Java compiler produces an intermediate bytecode format that is machine
independent. This, in turn, is processed at run time by a Java interpreter. The
interpreter also inspects the bytecode at run time to ensure its validity and
safety to the machine environment. Because of the isolation the Java
interpreter provides, it is sometimes referred to as a Java Virtual Machine
(JVM).
The Java language can be used to construct Java servlets, Java applets, and Java
applications.
Java applets
Java applets are supported for compatibility with previous versions of 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 servlets
Java servlets are small Java applications that run on a Web server machine,
unlike Java applets, which are downloaded to a Web browser.
Java servlets have become popular as a replacement for CGI (Common
Gateway Interface) programs. The advantage of Java servlets over CGI
applications is that they can execute more quickly since they are invoked as
threads in a daemon process, meaning that they are persistent in memory and
can fulfill multiple requests.
Note that servlets must ensure references to the gateway objects are
thread-safe.
Java technology
Chapter 1. Overview 11

Java technology
Java applications
A Java application is a program that executes locally on a computer. It has
operating system dependent capabilities in addition to those of an applet. It
can access local files, create and accept general network connections, and call
native C or C++ functions in machine-specific libraries.
Java applications can use the CICS-provided Java classes to perform
transaction processing in CICS systems. They can use the JavaGateway class
to establish two kinds of connection:
v A network gateway connection is a connection across a network to a CICS
Transaction Gateway.
v A local gateway enables a Java application to communicate directly with a
CICS Transaction Server, without the need for a network.
When the connection between the application and the CICS Transaction
Gateway has been established, an application can use the ECIRequest class,
for example, to do transaction processing.
Firewalls
A current design consideration in the use of Java applet communication is the
impact of firewalls. This is the term given to a configuration of software that
prevents unauthorized traffic between a trusted network and an untrusted
network. Firewalls are put in place to protect company assets from outside
intrusion, but they can also limit legitimate communications. Firewalls have
two functions:
1. To restrict access to a server by outside users - inbound restrictions
2. To limit the ability of users inside a firewall to perform certain network
functions outside their firewall - outbound restrictions.
A CICS Transaction Gateway configuration is well suited to avoid problems in
the first area since the Gateway processor can be placed outside the firewall
and be connected through the firewall to the CICS server. Outbound firewalls
that users may have to contend with can be a problem. A large company
might use a firewall to limit the types of connections and protocols that can
be used.
The use of Java on an intranet (a local implementation of the Internet) works
very well since firewalls are typically not a factor. If you are designing
applications to run over the Internet (rather than an intranet), determine
whether your potential users are behind firewalls. If so, consider alternative
processing for those users, such as executing the Java code as a Java servlet
on the Web server. Also consider using HTTP and HTTPS protocols supported
by CICS Transaction Gateway, see “Authentication using SSL” on page 8 and
“HTTPS” on page 10.
12 CICS Transaction Gateway: z/OS Administration

Java technology
Web servers
A Web server is a software program that responds to information requests
generated by Web browsers. When a request from a browser is received, the
Web server processes the request to determine the action to take:
v Return the requested document.
v Deny the request.
v Pass the request through for further processing by an external application.
The request might be, for example, to a database to perform a search
request, or to a more dynamic form of information delivery such as Lotus ®
Domino .
Communication between a Web server and an external application is
transparent; you need to know only the URL of the Web server to direct a
request to it. Also, all Web servers can handle requests from many browsers
concurrently.
Specialized servers can also be configured to limit access to a restricted set of
users, or to provide security for purchase of goods or services.
Web servers exist for almost every operating system and are available from
many suppliers. For information on the Web servers supported by CICS
Transaction Gateway, see “Software requirements” on page 20.
The J2EE resource adapters
An API in the CICS Transaction Gateway allows Java programmers to take
advantage of features provided in J2EE-compliant runtime environments (e.g.
IBM WebSphere Application Server). The J2EE resource adapter defines a
standard architecture for connecting the Java 2 Platform, Enterprise Edition
(J2EE) to heterogeneous Enterprise Information Systems (EIS) such as CICS.
The resource adapter architecture defines a set of scalable, secure, and
transactional mechanisms that enable the integration of EISs with application
servers and enterprise applications.
A proprietary application server, such as IBM WebSphere, can be extended to
support the resource adapter architecture, and is then assured of a seamless
connectivity to multiple EISs. Similarly, a vendor provides a standard resource
adapter that can connect any application server that supports the resource
adapter architecture to an EIS.
The resource adapter architecture defines a Common Client Interface (CCI) for
EIS access. The CCI defines a client API for interacting with heterogeneous
EISs. The resource adapter architecture enables a vendor such as IBM to
provide a standard resource adapter to allow access to its product. This
Chapter 1. Overview 13

Introduction
resource adapter connects 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 which are provided.
The samples.txt file, in the \samples subdirectory, provides
additional information on the J2EE sample programs.
How CICS Transaction Gateway accesses CICS
This section describes how CICS Transaction Gateway allows Java servlets to
access CICS programs and data.
1. The Web server loads and initializes the servlet. This could be when the
Web server starts, or when the first request is made to the servlet by the
Web browser or network computer.
2. The servlet creates a JavaGateway object to connect to the CICS
Transaction Gateway. This establishes communication between the browser
and the long running Gateway daemon process using Java’s sockets
protocol.
3. When a HTTP request from the Web browser or network computer
invokes the servlet, the Web server calls its Service method with details of
the request.
4. The servlet creates an ECIRequest object, that contains ECI calls, and
sends it to the CICS server using the JavaGateway.flow method.
5. The CICS server processes the calls, including verification of the userid
and password if required, and passes control and user data to the CICS
application program.
6. When the CICS application program has finished processing, it returns
control and data to CICS.
7. The CICS server returns control and data to the Java servlet.
8. When the servlet receives the results, it generates a HTTP response to
return to the Web browser.
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 clients. The threading model uses the following objects:
14 CICS Transaction Gateway: z/OS Administration

ConnectionManagers
A ConnectionManager manages all the connections from a particular Java
client. When it receives a request, it allocates a Worker thread from a pool of
available Worker threads to execute the request.
Workers
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.
You can set both the initial and maximum sizes of the resource pools for these
objects; see “General Gateway settings” on page 56 for information on setting
configuration parameters. You can also specify these limits when you start the
CICS Transaction Gateway, see “Starting from a command line” on page 117.
Table 3 shows thread limits that should be considered when setting the
number of Connection Manager and Worker threads on the various operating
systems:
Table 3. Thread limits on CICS Transaction Gateway operating systems
Operating
system
System-wide limit of
the maximum number
of threads
z/OS This may be restricted
by the total number of
MVS ® Task Control
Blocks (one is created
per UNIX System
Services thread)
Process limit of the number of threads
Governed by the UNIX System Services
parameters: MAXTHREADS and
MAXTHREADTASKS
Windows No limit Limited by the amount of virtual memory
available for the process (by default a
thread has 1M of stack meaning that 2028
threads can be created per process)
AIX 262 143 32 768
HP-UX No limit (30 000 kernel
threads)
Linux Equal to the maximum
number of processes
The CICS Transaction Gateway: threading model
Solaris No limit No limit
30 000 (refer to Configurable Kernel
Parameters in the SAM utility)
1024 (refer to your LinuxThreads
documentation for more information)
You can determine what values have been set for the UNIX System Services
parameters MAXTHREADS and MAXTHREADSTASK by examining the
Chapter 1. Overview 15

The CICS Transaction Gateway: threading model
Applet/application
JavaGateway.open
JG.flow(ECIRequest)
appropriate BPXPRMxx member of SYS1.PARMLIB. For more information
about these parameters, refer to the Z/OS UNIX System Services Planning book.
For more information on the way Java allocates memory for threads, refer to
“Performance issues” in the CICS Transaction Gateway: Programming Guide
book.
The threading model is illustrated in the following figures:
Network
handshake
tcp:/ssl:
Protocol
handlers
CICS Transaction Gateway
Connection
managers Workers
ready for
new work
EXCI
wait
CICS
server
Figure 4. CICS Transaction Gateway threading model for TCP/IP and SSL. These protocols have a persistent socket.
16 CICS Transaction Gateway: z/OS Administration
EXCI
reply

Applet/application
JavaGateway.open
JG.flow(ECIRequest)
Network
handshake
http:/https:
Protocol
handlers
CICS Transaction Gateway
Connection
managers Workers
ready for
new work
EXCI
wait
CICS
server
EXCI
reply
Figure 5. CICS Transaction Gateway threading model for HTTP/HTTPS. These protocols do not have a persistent
socket.
Chapter 1. Overview 17

18 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
Chapter 2. Planning your installation
This chapter helps you plan the installation of the CICS Transaction Gateway
for z/OS by listing the software, Web Servers and browsers that are
supported. It also has information for those who are using an earlier version
of the product.
For information on supported software and hardware requirements for other
CTG platforms, see Appendix A, “Hardware and software” on page 155.
“Disk space requirements” Read this for information on disk space
needed to install and run the CICS
Transaction Gateway.
“Software requirements” on page 20 Read this for information on the software
you need to run the CICS Transaction
Gateway.
“Checking the z/OS shell environment”
on page 22
Read this for information on how to
check that your z/OS shell environment
is set up correctly.
“National Language Support” on page 22 Read this for information on languages
that are supported.
“Migrating from CICS Gateway for Java
(MVS)” on page 23
“Migrating from CICS Transaction
Gateway for OS/390 Version 3” on
page 24
Read these if you currently using an
earlier version of CICS Transaction
Gateway.
See the product readme file for any late changes to hardware and software
requirements.
If you are installing from CD, the readme file is README.ZOS in the root
directory.
If you have downloaded the product, the packaged file that you downloaded
contains the product code and the readme file for your operating system.
Disk space requirements
CICS Transaction Gateway is normally installed into a directory such as
/usr/lpp/ctg, in USS (see also “Installation path” on page x). In this case,
during installation, the uncompressed tar file is present in the /usr/lpp
directory. The HFS data set for this directory must be large enough to take the
© Copyright IBM Corp. 1996, 2002 19

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Disk space requirements
25MB (40 cylinders) that this file occupies. You can delete the files once
installation is complete. Installation also requires 25MB (40 cylinders) in the
/tmp directory.
Once installed, CICS Transaction Gateway occupies 27MB. You need enough
disk space for CICS Transaction Gateway and any logging and tracing files.
IBM recommends that you use a separate HFS data set with a primary
allocation of 40 cylinders for CICS Transaction Gateway software. Increase this
to 50 cylinders if the logging and trace files will be stored in the same HFS
data set. Increase it further if many instances of CICS Transaction Gateway
will run, or if much logging is required. Alternatively, you can use a separate
HFS data set, with a primary allocation of 5 cylinders, for each instance of
CICS Transaction Gateway.
If you use the existing /usr/lpp HFS data set, ensure it has enough space to
take the CICS Transaction Gateway software.
Software requirements
The following products are supported.
Operating systems
CICS Transaction Gateway is supported on the following operating systems:
v OS/390 V2.10
v z/OS V1.2
Web browsers
v HTML/HTTP functions: Any browser that supports HTML V1.0 should
work with the product.
v Java Functions: Any JDK 1.1 compliant Web browser should work with the
product.
The CICS Transaction Gateway is supported with the following browsers:
v Microsoft ® Internet Explorer 5.0, 5.5 and 6.0
v Netscape Communicator 4.7 and 6.2
Note: Applets running within the JVM supplied with the Netscape
Communicator browser fail to make successful connections with the
CICS Transaction Gateway. Message number CCL6652E is returned to
the applet. Currently there is no solution to this problem.
Java applets are supported for compatibility with previous versions of
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.
20 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
JDK levels
CICS Transaction Gateway supports JDK levels 1.3 and 1.3.1 at the following
minimum service levels:
v z/OS: IBM Java SDK 1.3
If using the IBM Persistent Reusable JVM, you are recommended to run at a
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable
functionality of this JVM.
If using Java under DBCS code pages, especially IBM-939, install service
refresh 14 or later.
JSSE
Software requirements
CICS Transaction Gateway supports JSSE in the the following environments:
v Standard Java runtime environment (JRE).
Only the IBM JSSE is supported:
– z/OS with JRE 1.3.1: includes a version of JSSE that CICS Transaction
Gateway supports
v WebSphere Application Server:
All supported levels have built in JSSE support.
CICS Transaction Gateway does not support the use of JSSE with applets.
CICS Servers
A CICS server runs real-time multi-user applications and manages the
associated resources and data. CICS Transaction Gateway is supported with
the following servers:
v CICS Transaction Server for z/OS V2.2
v CICS Transaction Server for z/OS V2.1 (with APAR PQ30168, for signon
capable terminals, applied)
v CICS Transaction Server for z/OS V1.3 with APAR PQ30168, for signon
capable terminals, applied. Apply z/OS APAR PQ38644, for EXCI, if you
are using the CICS Transaction Gateway for z/OS.
Web servers
Any web server that is supported by your application server should work
with the product.
Application servers
The CICS Transaction Gateway is supported with the following:
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF
UQ99329 (Service Level W401030).
Chapter 2. Planning your installation 21

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Checking the z/OS shell environment
Checking the z/OS shell environment
1. Before you install CICS Transaction Gateway, ensure that the z/OS shell
environment is set up correctly. The default system-wide user environment
is specified in the /etc/profile file. User overrides to this are in the user’s
~/.profile file. Check the following:
v The PATH statement includes the binary directory where java is located,
for example:
export PATH=/usr/lpp/java/J1.3/bin:$PATH
If you are also running an older version of CICS Transaction Gateway,
the path to JDK 1.3 must appear before the JDK for the older version of
CICS Transaction Gateway.
v The JAVA_COMPILER environment variable is set to jitc and the
LIBPATH is set appropriately, if the Java JIT compiler is to be used.
Note: JIT compilers may cause problems with the HTTPS and SSL
protocols and therefore may need to be disabled if you wish to
use these secure protocols.
export JAVA_COMPILER=none
2. If you will run CICS Transaction Gateway applications in local mode, or
you have set AUTH_USERID_PASSWORD to Yes, set the following
environment variable, in the environment under which the Java
applications will run:
JAVA_PROPAGATE=NO
If you do not do this, ECI calls will fail with an
ECI_ERR_SECURITY_ERROR return code.
For more information about setting the z/OS shell environment, see the Z/OS
UNIX System Services User’s Guide, SC28-1891 book.
National Language Support
Only English, Japanese and Simplified Chinese are supported. (These are the
languages supported by CICS Transaction Server for z/OS.) See Appendix B,
“Supported code pages” on page 163 for supported code pages.
Coexistence with other products
WebSphere Application Server for OS/390 v3.5
WebSphere Application Server for OS/390 v3.5 fully supports servlets that
use the CICS Transaction Gateway Common Connector Framework (CCF)
ECI connector or ECIRequest class, but does not support the J2EE CICS
ECI connector.
22 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Coexistence with other products
WebSphere Application Server for z/OS v4.0 plugin
The plugin provides a WAS v3.5 SE runtime environment that fully
supports v3.5 servlets that use the CICS Transaction Gateway CCF ECI
connector or ECIRequest class. You are recommended to run existing
applications under the plugin. The J2EE CICS ECI connector is not
supported within this environment. The plugin is provided for migration
purposes only.
WebSphere Application Server for z/OS v4.0 runtime migration issues
Under the WAS v4.0 Runtime environment, the following restrictions
apply:
1. In the WAS v3.5 environment (or under the WAS v4.0 Plugin), the
userid that has been authenticated by the HTTP server is automatically
passed to CICS when using the CCF ECI connector or ECIRequest
class, if a null userid and password are specified on the ECI call. This
mechanism does not work under the WAS v4.0 Runtime environment
as the authenticated userid is not available on the ACEE associated
with the WebSphere thread on which the CTG runs in local mode.
2. The WAS v4.0 Runtime provides limited support for CCF CICS
Connector and ECIRequest calls that form part of an extended LUW.
These calls must all be issued from the same thread, otherwise an
error of ECI_ERR_LUW_TOKEN will be returned. Also, there must
only be one outstanding LUW on any given thread at a time.
For CCF solutions, it is recommended that you use the WAS v4.0 Plugin
and then migrate to using J2EE.
If you are using the ECIRequest class extended LUW mode, it is
recommended that you use the WAS v4.0 Plugin and then migrate to J2EE
or to a non-extended LUW solution.
There is a new EciRequest class method SetGlobalTranSupport. If this
method is called on a non-extended ECIRequest, and a global transaction
is associated with the current RRS context, the request will join the global
transaction. Otherwise the request will be issued with sync on return. This
gives two-phase commit capability.
Migrating from CICS Gateway for Java (MVS)
If you have customized the Gateways.properties or the JGate script, save a
copy of them before you install CICS Transaction Gateway for z/OS.
In CICS Transaction Gateway for OS/390 Version 3.1, the Gateway.properties
file was renamed to CTG.INI and the JGate script to ctgstart. Convert old
Chapter 2. Planning your installation 23

|
|
|
|
|
|
|
|
|
|
|
Migrating from CICS Gateway for Java (MVS)
Gateway.properties files to the new format. See “Using the configuration tool”
on page 52 for the new settings, and refer to the CTGSAMP.INI file for the
correct format.
Change all import statements in your programs and recompile them. Change
all occurrences of:
import ibm.cics.jgate.client.* to: import com.ibm.ctg.client.*
import ibm.cics.jgate.security.* to: import com.ibm.ctg.security.*
Due to a change in the ClientSecurity and ServerSecurity interfaces, any user
classes that implement these interfaces need to be changed. The TCP/IP
address of the remote computer is now passed to the methods called to
generate handshake data. An afterDecode method has also been added to
both interfaces.
Migrating from CICS Transaction Gateway for OS/390 Version 3
If you have customized the JGate script (used to set environment variables),
save a copy before you install CICS Transaction Gateway for z/OS Version
Version 5.0.
In Version 3.1, the Gateway.properties file was renamed to CTG.INI, and the
JGate script to ctgstart. Convert old Gateway.properties files to the new
format. See “Using the configuration tool” on page 52 for the new settings,
and refer to the CTGSAMP.INI file for the correct format.
Migrating from CICS Transaction Gateway Version 4
Delete file /license before attempting to install Version 5.0.
This file contains license information for version 4 of the CICS Transaction
Gateway. ctginstall creates a directory called /license to
store license information for Version 5. If a file of the same name exists,
ctginstall cannot create the directory, and the installation fails.
24 CICS Transaction Gateway: z/OS Administration

Chapter 3. Installation
This chapter describes how to install CICS Transaction Gateway for z/OS. It
consists of the following:
Table 4.
“Installation: overview” on page 26 Read this for an overview of the steps
involved in installing the CICS
Transaction Gateway.
“Installation: detail” on page 27 Read this for detailed instructions on how
to install the Gateway.
“Installing into a locale other than 1047
(U.S. English)” on page 32
Read this for information about installing
in Japanese or Simplified Chinese.
“Directory structure” on page 33 Read this for information on the directory
structure that is created during
installation.
“Uninstalling the CICS Transaction
Gateway for z/OS” on page 34
“Using X-Windows from a remote
system” on page 34
“Extracting and installing the PDF
library” on page 35
Read this if you want to uninstall the
CICS Transaction Gateway.
Read this for information on how to
access z/OS applications from a remote
system.
Read this for information on how to view
the manuals on the CD.
“Service and updates” on page 36 Read this for information on obtaining
service and updates to the program.
© Copyright IBM Corp. 1996, 2002 25

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation
Installation: overview
The CICS Transaction Gateway is provided as the compressed file
ctg-500m.tar.Z, which contains the CICS Transaction Gateway software that is
to be installed in the hierarchical file system (HFS). This section outlines the
steps that you need to take to install the software on your system. For
detailed instructions see “Installation: detail” on page 27.
v If you are installing into a test environment, you can omit steps marked
(Optional) . Step 2 is optional, because you do not need to create a
separate HFS data set for installation into a test environment.
v If you are installing into a production environment, follow all the steps in
“Installation: detail” on page 27. In a production environment, you are
recommended to install into a separate HFS data set.
__ Step 1. Step 1: Gather information and obtain the necessary permissions.
__ Step 2. Step 2: (Optional) Make a safe home for the CICS Transaction
Gateway. You will install the CICS Transaction Gateway into this
data set.
__ Step 3. Step 3: Upload, unpack and install.
After you have installed the CICS Transaction Gateway, follow these steps to
configure and test your installation:
__ Step 4. Configure your CICS Transaction Server for z/OS; see Chapter 4,
“Configuring the CICS Transaction Server for z/OS” on page 37.
__ Step 5. Configure your CICS Transaction Gateway by creating files:
v CTG.INI
v ctgenvvar
See “Editing the sample configuration files” on page 43.
__ Step 6. Test your configuration; “Testing your configuration” on page 117.
You are recommended to print the instructions, and check off completed steps
in the “Installation: overview” section.
OMVS features
Some responses take a long time to complete, and the terminal mode changes
from RUNNING to INPUT before the command has finished. If you see
INPUT in the bottom right of your screen, press ENTER to receive more
output.
26 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation: detail
This section gives detailed instructions on installing the CICS Transaction
Gateway.
Step 1: Gather information and obtain the necessary permissions
You are recommended to record the following:
Variable Explanation Required
in
The directory to which your CICS
Transaction Gateway will be
installed. This is always
/ctg
The directory to which you will
upload the CICS Transaction
Gateway, for example usr/lpp
The HFS data set where the CICS
Transaction Gateway will be kept,
for example OMVS.USR.LPP.CTG500
The HFS dataset which will be
used for the logs, for example
OMVS.USR.LPP.CTGLOGS
The Netname for the MRO
connection on CICS.; see Figure 6
on page 38. This is the same as
the DFHJVPIPE environment
variable, set through ctgenvvar.
See Figure 6 on page 38; the CICS
that appears in the
bottom right of the CEDA
transaction screen.
The location of the installed CICS
EXCI load library, for example,
CICSTS22.CICS.SDFHEXCI
The location of any optional user
override options for EXCI, for
example, USERID.LOAD.LIB
Steps 2
and 3.
Steps 2
and 3.
Your value
Step 2 (Optional)
Step 2 (Optional)
Steps 4
and 5
Steps 4
and 5
Step 5
Step 5
Installation
You need to be logged in as root, or have superuser authority (UID=0) to
perform the steps marked (Optional)
Chapter 3. Installation 27

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation
For the CTG and logs datasets, you are recommended to use a naming
convention that reflects the location of the datasets in the USS structure, and
that allows for different versions of the CICS Transaction Gateway. If the
for CICS Transaction Gateway Version 5.0 is /usr/lpp/ctg, the
following names would be suitable:
OMVS.USR.LPP.CTG500
OMVS.USR.LPP.CTG.LOGS
The HFS data set that you choose to allocate to hold the CICS Transaction
Gateway HFS can be any data set name, but to mount it into the root file
system the UNIX System Services kernel task must have UPDATE access to
the data set that you create. Normally, the high-level qualifier that you use for
(shown as OMVS in the example), is the same as that for the
HFS data set of the root file system. Consequently RACF will probably
already allow OMVS the necessary access to data sets with that high-level
qualifier. However, if you choose a data set high-level qualifier that differs
from that of the root file system you must issue RACF commands to give the
OMVS kernel task userid UPDATE access to your CICS Transaction Gateway
HFS data set.
You have completed this step. Mark as completed checklist Step 1 on page 26.
Step 2: (Optional) Make a safe home for the CICS Transaction Gateway
The “Installation: overview” on page 26 section explains why this step is
optional.
Stage A — make the directory
The directory is always the ctg subdirectory of the
. Create this directory if it does not already exist, using one of
these methods:
OMVS and Telnet
1. Issue this command to change to the :
cd
2. Create the subdirectory:
mkdir ctg
3. Allow yourself read and write access to the directory. Other users have
read access:
chmod 755 ctg
TSO ISHELL
1. Issue the command N, for new.
2. On the Create a New File dialog box, set the following:
28 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Pathname :
Permissions :755
File type :1 (Directory)
The command fails if the does not already exist, or you
do not have permission to write to it. In these cases:
v Modify the steps above to create the directory; or
v Request write permissions from the owner of the directory
Stage B — create and mount an HFS data set to hold the CICS
Transaction Gateway
requires 25 MB, or 40 cylinders. Sample JCL, which does
everything in this stage, is provided in file
/samples/CTGMAKE.JCL; this file is available if you have
previously installed into a test environment.
1. Use either TSO or ISPF to create the data set.
TSO
Issue the following command:
ALLOC DA(’’) DSNTYPE(HFS) SPACE(40,5) DSORG(PO) CYL
ISPF
a. Use the Data Set Utility screen (option 3.2):
Option : A
Dataset name : ’’
b. Set the following on the Allocate New Data Set screen:
Space Units :CYLS
Primary quantity :40
Secondary quantity :5
Data set name type :HFS
2. Use the following TSO command to mount the data sets in to existing
directories:
MOUNT TYPE(HFS)
MODE(RDWR)
MOUNTPOINT(’’)
FILESYSTEM(’’)
3. The mount will be lost at the next IPL. To mount the data set permanently,
add the above command to the member BPXPRMxx in SYS1.PARMLIB,
where xx is the suffix referenced by the BPX= option in the IEASYSxx
member of SYS1.PARMLIB.
Stage C — make the /logs directory
This has to be done now as mounting the in “Stage B —
create and mount an HFS data set to hold the CICS Transaction Gateway”
replaces any data already in the .
Use one of these methods to create the directory, if it does not exist:
Installation
Chapter 3. Installation 29

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation
OMVS and Telnet
1. Issue this command to change to the :
cd
2. Create the subdirectory:
mkdir logs
3. Allow yourself read and write access to the directory. Other users have
read access:
chmod 755 logs
TSO ISHELL
1. Issue the command N, for new.
2. On the Create a New File dialog box, set the following:
Pathname :/logs
Permissions :755
File type :1 (Directory)
The command fails if the does not already exist, or
you do not have permission to write to it. In these cases:
v Modify the steps above to create the directory; or
v Request write permissions from the owner of the directory
Stage D — create and mount an HFS data set to hold the logs
1. Use either ISPF or TSO to create the dataset.
requires less than 5 MB, or 5 cylinders, for each CICS
Transaction Gateway running. Increase the primary allocation if you will
run more than one instance of the CICS Transaction Gateway.
TSO
Issue the following command:
ALLOC DA(’’) DSNTYPE(HFS) SPACE(5,5) DSORG(PO) CYL
ISPF
a. Use the Data Set Utility screen (option 3.2):
Option :A
Dataset name :’’
b. Set the following on the Allocate New Data Set screen:
Space Units :CYLS
Primary quantity :5
Secondary quantity :5
Data set name type :HFS
2. Use the following TSO command to mount the log data set:
MOUNT TYPE(HFS)
MODE(RDWR)
MOUNTPOINT(’//logs’)
FILESYSTEM(’’)
30 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3. The mount will be lost at the next IPL. To mount the data set permanently,
add the above command to the member BPXPRMxx in SYS1.PARMLIB,
where xx is the suffix referenced by the BPX= option in the IEASYSxx
member of SYS1.PARMLIB.
You have completed this step. Mark as completed checklist Step 2 on page 26.
Step 3: Upload, unpack and install
Installation
1. To upload file ctg-500m.tar.Z, mount the CD on either a workstation
connected to the System/390 ® , or another system with access to the
System/390. Use one of the following methods to upload the file:
Workstation file transfer
a. Pre-allocate a data set of 30 cylinders to hold the compressed file,
for example CTG-500M.TAR.Z.
b. Upload the file to that data set, using the terminal emulator
transfer options for a binary file.
c. Use the OPUT command on TSO to put the data set in HFS, for
example:
OPUT ’CTG-500M.TAR.Z’ ’/ctg-500m.tar.Z’ BINARY
FTP
v Use an FTP client to upload the compressed TAR file to the
directory.
v Specify an HFS (not z/OS) data set as the destination.
v Transfer the file in binary mode.
v Do not specify any attributes appropriate to a z/OS data set, such
as lrecl.
2. To uncompress the file, use these commands from an OMVS or Telnet
screen:
cd
uncompress ctg-500m.tar.Z
3. To extract the file that you uncompressed in the previous step, use the
command
tar -xopvf ctg-500m.tar
where:
v -x specifies that all files are extracted.
v -o allows the original file permission bits for owner, group and all to be
restored. This is useful for all the execute bits.
v -p does not try to restore the original owner and group id when
extracting files. The default is to do this, but most likely the person
doing the extract will not have permission, or the user id will not exist
on the system.
Chapter 3. Installation 31

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Installation
v -v specifies verbose messages (optional). This generates many messages,
but gives useful information on what is happening.
v -f Specifies the file name of the archive file.
4. Use a program like OEDIT to view file /ctginstall.readme,
containing the latest instructions on installation.
5. Type ctginstall to begin installation. The script checks the level of z/OS
you have installed.
If any of the prerequisites are not available, the ctginstall script generates
information messages and terminates. Fix any problems before you run the
script again.
6. Type 1 to continue installation by reading and accepting the license
agreement. You must accept the license to install the product; if you select
2 the installation program ends.
Note: If the word INPUT appears in the bottom right corner of your
screen while you are reading the license, press Enter to continue
viewing.
7. If the agreement does not display properly, restart the installation using
the command ctginstall 40. This sets your screen width to 40 characters
during installation.
After you have accepted the agreement, the CICS Transaction Gateway is
installed into the directory. All necessary subdirectories are
created.
8. Print and read the README.TXT file, which may contain information not in
the books.
9. (Optional) Create a job if you want to run the Gateway as a batch job.
You can use the sample JCL at “Starting with JCL” on page 121 as a
starting point.
You have completed your installation. Mark as completed checklist Step 3 on
page 26.
Installing into a locale other than 1047 (U.S. English)
You can install the CICS Transaction Gateway for z/OS in Japanese or
Simplified Chinese, but the limitations of Unix System Services (USS) and the
EBCDIC character set require you to take extra steps. See
/ctginstall.readme for details of converted versions of the
ctginstall script.
Whichever locale is used, the datastream flows between a client application
and CICS Server are not affected.
32 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
See “The configuration tool” on page 139 for restrictions on using the
configuration tool in DBCS environments.
Changing the code page after installation
Whether installed as IBM-1047 or another code page (code set), the installation
can be converted to another code page by running the command:
/bin/ctgmsgs
in the current code page of the installation. To display the supported language
and code set combinations, issue the command:
/bin/ctgmsgs -?
Directory structure
The following is the directory structure of the installed CICS Transaction
Gateway:
Table 5. Contents of directories
Relative path Contents
A ctg subdirectory in a location defined
by the user. For example:/usr/lpp/ctg.
/bin CICS Transaction Gateway executable
code.
/classes Java classes.
/deployable RAR files.
/docs Documentation for the CICS Transaction
Gateway. This contains the documentation
Library in PDF format, and the javadoc
directory.
/license License files. To view your license, issue
the command ctgbrowse. If the agreement
does not display properly, issue the
command ctgbrowse 40. This sets your
screen width to 40 characters while you
are viewing the agreement.
/msgs NLS message files, used by scripts.
/samples Java source files for samples.
/bin/resource NLS resource files.
After installation, you may want to browse these files in the
/bin subdirectory:
CTGSAMP.INI Sample configuration file
Installation
Chapter 3. Installation 33

|
|
|
|
|
|
|
|
|
|
Installation
ctgenvvarsamp Sample environment variables file
ctgcfg Script to start configuration tool
ctgikey Script to start ikeyman
ctgstart Script to start the CICS Transaction Gateway
itself.
The files in the /samples/java/com/ibm/ctg/samples/security
subdirectory contain samples to demonstrate the basic functionality of the
CICS Transaction Gateway security exits. The samples demonstrate
compression of the client/server data flows using the java.util.zip package.
Uninstalling the CICS Transaction Gateway for z/OS
To uninstall CICS Transaction Gateway, use this command:
/bin/ctguninst
Using X-Windows from a remote system
You can use X-Windows on a remote system to access applications under
z/OS. The X-Windows System is a network-transparent protocol that supports
windowing and graphics. The protocol is communicated between an X client
(application) and an X server over a TCP/IP network. X-Windows support is
provided as part of the AIX product, and on Windows platforms by, for
example, the Hummingbird ® Exceed product.
In an X-Windows System environment, the X server is usually located on the
workstation, and this distributes user input to, and accepts requests from, one
or more X client programs located either on the same system or elsewhere on
a network. This is an important point, as z/OS users will usually regard
anything that runs on the host as the server and any application on the
workstation as the client.
Java and UNIX System Services do not fully support GUI (Swing and AWT
based) applications running in double byte character systems (Japanese and
Simplified Chinese). They do not provide easy access to the correct fonts. In
this environment you can use the configuration tool only in English. Start it
with the -LANG US option:
ctgcfg -LANG US
When using X-Windows from a remote system, for example, to access the
configuration tool and iKeyman, you must set up the DISPLAY environment
variable to allow the application to display its windows on that system.
34 CICS Transaction Gateway: z/OS 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:
DISPLAY=disp:0.0
followed by
export DISPLAY
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.
To find the IP address on Windows platforms, enter the ipconfig command.
To find the host name on UNIX platforms, enter the hostname command.
You can add the statement:
export DISPLAY=disp:0.0
to your .profile file.
Extracting and installing the PDF library
Using X-Windows from a remote system
The PDF library (CTG_Library.pdf) for CICS Transaction Gateway is located in
the /docs subdirectory.
Transfer the library to a system that can run the Adobe Acrobat Reader.
(Currently no Adobe Acrobat Reader is available for z/OS.) For information
about the Adobe Acrobat Reader, see www.adobe.com.
If you have the product CD-ROM, you will also find this PDF book in the PDF
directory.
To transfer the PDF file to a Windows workstation, use FTP in binary mode,
or proceed as follows:
1. Use ISPF option 3.2 to allocate a data set with the name
userid.CTGLIB.PDF, and which has the following attributes:
Chapter 3. Installation 35

Using X-Windows from a remote system
Service and updates
Organization . . . : PS
Record format . . . : VB
Record length . . . : 32756
Block size . . . . : 32760
1st extent tracks . : 170
Secondary tracks . : 10
2. Enter the TSO command:
OGET ’/docs/CTG_Library.pdf’
’userid.CTGLIB.PDF’ BINARY
to copy the CTG_Library.pdf file from UNIX System Services to the z/OS
sequential data set userid.CTGLIB.PDF.
3. Transfer userid.CTGLIB.PDF to your workstation, either by using FTP, or:
a. Go to TSO READY on the z/OS system.
b. Select Transfer on the top bar.
c. Select Receive Files from Host.
d. Specify:
Host file : ’userid.CTGLIB.PDF’
PC file : C:\temp\CTG_Library.pdf
Transfer type : binary
and select RECEIVE. When the RECEIVE has completed, you should
have file CTG_Library.pdf in the temp directory on your workstation.
You can then delete userid.CTGLIB.PDF from the z/OS system.
Service and updates are available at the following Web site:
www.software.ibm.com/ts/cics/support/details
36 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
Chapter 4. Configuring the CICS Transaction Server for
z/OS
This chapter describes how to configure EXCI connections, to allow the CICS
Transaction Gateway to connect to a CICS region. It contains these topics:
“CICS server connection definition” Read this for information on defining
connections.
“CICS server sessions definition” on
page 40
“Open interregion communication” on
page 42
“EXCI user-replaceable module
DFHXCURM” on page 42
For each connection, you need to provide
information about the sessions.
After you have defined your connections
and session, you need to install the group
and set interregion communication open.
You might also wish to modify the EXCI
user-replaceable module DFHXCURM.
CICS server connection definition
CICS Transaction Server provides example EXCI connection and session
definitions (EXCG and EXCS) in the sample group DFH$EXCI. You can
choose to:
v Use them as they are; or
v Copy them to form the basis of your own definitions; or
v Create your own definitions using the instructions that follow
The following are examples of a connection definition:
© Copyright IBM Corp. 1996, 2002 37

|
|
|
|
|
|
CICS Transaction Server for z/OS
VIEW GROUP(MYEXCI) CONNECTION(JCOS)
OBJECT CHARACTERISTICS CICS RELEASE = 0620
CEDA View Connection( JCOS )
Connection : JCOS
Group : MYEXCI
DEscription : Sample EXCI Specific connection
CONNECTION IDENTIFIERS
Netname : JGATE400
INDsys :
REMOTE ATTRIBUTES
REMOTESYSTem :
REMOTEName :
REMOTESYSNet :
CONNECTION PROPERTIES
ACcessmethod : IRc Vtam | IRc | INdirect | Xm
PRotocol : Exci Appc | Lu61 | Exci
Conntype : Specific Generic | Specific
SInglesess : No No | Yes
DAtastream : User User | 3270 | SCs | STrfield | Lms
+ RECordformat : U U | Vb
SYSID=CW2C APPLID=IYCWZCFY
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL
Figure 6. Connection definition—screen 1
OBJECT CHARACTERISTICS CICS RELEASE = 0620
CEDA View Connection( JCOS )
Queuelimit : No No | 0-9999
Maxqtime : No No | 0-9999
OPERATIONAL PROPERTIES
AUtoconnect : No No | Yes | All
INService : Yes Yes | No
SECURITY
SEcurityname :
ATtachsec : Identify Local | Identify | Verify | Persistent | Mixidpe
BINDPassword : PASSWORD NOT SPECIFIED
BINDSecurity : No No | Yes
Usedfltuser : No No | Yes
RECOVERY
PSrecovery : Sysdefault | None
Xlnaction : Keep Keep | Force
SYSID=CW2C APPLID=IYCWZCFY
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL
Figure 7. Connection definition—screen 2
The relevant parameters (shown in bold in the figures) are:
Netname
If you enter a Netname, the connection will use a specific pipe. If you
leave it blank, the EXCI connection will use a generic pipe. Generally it is
best to use a specific pipe, since this helps to manage multiple
connections, and to identify problems.
38 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CICS Transaction Server for z/OS
If you use specific pipes, set Netname to be the same as the pipe specified
in the EXCI client program. (This is specified on the user_name parameter
of an Initialize_User EXCI call.) Set the DFHJVPIPE environment variable
to allow the CICS Transaction Gateway to pass this value to the EXCI; see
“Setting environment variables” on page 47.
Note: If you use the sample DFH$EXCI, set the DFHJVPIPE environment
variable to BATCHCLI to use the specific pipe.
If a CICS Transaction Gateway is configured to connect to more than one
CICS region, use the same Netname for all EXCI connections.
ACcessmethod
Specify IRC (interregion communication).
PRotocol
Specify EXCI.
Conntype
This defines the type of EXCI connection used for non-CICS jobs to
communicate with a CICS region on z/OS. It is a type of multiregion
operation (MRO) request and can be either Generic or Specific.
Generic
An MRO link with a number of sessions to be shared by multiple
EXCI users. Only one generic EXCI connection can be installed in each
region. Specify Generic if you left the Netname attribute blank.
Specific
An MRO link with one or more sessions dedicated to a single user in
a client program. Specify Specific if you completed the Netname
attribute.
ATtachsec
This causes a check to be made against the flowed user ID. Specify either
Local or Identify.
Local
The remote system does not flow a user identifier; only the link user
ID (if specified) is used. If no link user ID is supplied then all requests
are run under the CICS default user ID as specified in the DFLTUSER
SIT parameter.
Identify
A user ID is flowed on every request, but no password is expected, as
CICS trusts the user ID as having been already authenticated. For
security reasons verify the user ID and password with RACF before
the EXCI request is made. The userid is either:
v The user named in the ECIRequest object
Chapter 4. Configuring the CICS Transaction Server for z/OS 39

|
|
|
|
|
|
|
CICS Transaction Server for z/OS
v (If null) the user ID of the thread under which the Gateway request
runs.
For details of how to produce these definitions see the CICS External Interfaces
Guide.
CICS server sessions definition
For each EXCI connection definition, you create a sessions definition.
VIEW GROUP(MYEXCI) SESSIONS(JCOS)
OBJECT CHARACTERISTICS CICS RELEASE = 0620
CEDA View Sessions( JCOS )
Sessions : JCOS
Group : MYEXCI
DEscription : Sample EXCI Specific sessions definition
SESSION IDENTIFIERS
Connection : JCOS
SESSName :
NETnameq :
MOdename :
SESSION PROPERTIES
Protocol : Exci Appc | Lu61 | Exci
MAximum : 000 , 000 0-999
RECEIVEPfx : JG
RECEIVECount : 004 1-999
SENDPfx :
SENDCount : 1-999
SENDSize : 04096 1-30720
+ RECEIVESize : 04096 1-30720
SYSID=CW2C APPLID=IYCWZCFY
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL
Figure 8. Sessions definition—screen 1
40 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
OBJECT CHARACTERISTICS CICS RELEASE = 0620
CEDA View Sessions( EXC1SESS )
SESSPriority : 000 0-255
Transaction :
OPERATOR DEFAULTS
OPERId :
OPERPriority : 000 0-255
OPERRsl : 0 0-24,...
OPERSecurity : 1 1-64,...
PRESET SECURITY
USERId :
OPERATIONAL PROPERTIES
Autoconnect : No No | Yes | All
INservice : Yes No | Yes
Buildchain : Yes Yes | No
USERArealen : 000 0-255
IOarealen : 04096 , 04096 0-32767
RELreq : No No | Yes
DIscreq : No No | Yes
SYSID=CW2C APPLID=IYCWZCFY
PF 1 HELP 2 COM 3 END 6 CRSR 7 SBH 8 SFH 9 MSG 10 SB 11 SF 12 CNCL
Figure 9. Sessions definition—screen 2
CICS Transaction Server for z/OS
The relevant parameters (shown in bold in the figures) are:
Connection
This sessions definition is associated with the JCOS connection.
Protocol
Specify EXCI.
RECEIVEPfx
This is a one or two character prefix for the receive session names. CICS
creates the remainder of the four character names from the alphanumeric
characters A through Z, and 1 through 9. These two or three character
identifiers begin with the letters AAA, and continue in ascending
sequence until the number of session entries reaches the limit set by the
RECEIVECount value (in our example JGAA, JGAB, JGAC, and so on).
The default receive prefix is the < symbol.
RECEIVECount
This defines the number of sessions that receive before sending. Since all
EXCI sessions are receive sessions, this defines the number of pipes that
can be used simultaneously. Because the EXCI imposes a maximum of 100
pipes for each EXCI address space, set RECEIVECount to 100 or less,
unless multiple EXCI clients use the same EXCI connection to connect to
the same CICS region. This could be the case if cloned Gateway daemon
connect to the same CICS region.
SENDCount
Leave blank. Because EXCI sessions can only receive, there are no send
sessions.
Chapter 4. Configuring the CICS Transaction Server for z/OS 41

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CICS Transaction Server for z/OS
USERId
This defines the preset user identifier to be used for link security
checking. It provides an additional security check for each transaction in
addition to the flowed user ID. If you do not specify a preset user ID for
link security, CICS uses the flowed user ID.
Open interregion communication
After you install the CONNECTION definitions, set interregion
communication (IRC) open:
CEDA INSTALL GROUP(groupname)
to install the group containing the definitions, and:
CEMT SET IRC OPEN
to set IRC open. For more information refer to the CICS Resource Definition
Guide.
EXCI user-replaceable module DFHXCURM
The user-replaceable module DFHXCURM is invoked on EXCI Allocate_Pipe
requests, and also after detection of EXCI retryable errors. This occurs in one
of three circumstances:
v the target CICS region is not available
v there are no pipes available on the target CICS region
v IRC has not been active since the last initial program load (IPL)
In early releases of CICS Transaction Gateway, an EXCI pipe was established,
used, and deallocated, for each ECI flow. CICS Transaction Gateway now
creates a pipe only for the first ECI flow. Later calls then reuse this pipe. As a
result, it is no longer possible to perform workload management using the
EXCI user-replaceable module DFHXCURM, because the code would only be
called on the first ECI flow.
An alternative way of performing workload balancing, is to:
1. route all your ECI flows to the same CICS region
2. perform the routing there, using, for example, a round-robin approach to
distribution
Although reusing the same pipe for EXCI calls has an impact on previously
written workload management code, there are benefits in CICS Transaction
Gateway performance. This is because the Initialize_User and Allocate_Pipe
EXCI commands are only called once per server. In the past they were called
at the start of every ECI flow.
42 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
Chapter 5. Configuring the CICS Transaction Gateway
To configure the CICS Transaction Gateway, you create two files: ctgenvvar
and CTG.INI. You can create the files in either of the following ways:
v By running the configuration tool. This creates both files for you, and is the
recommended way if you have X-Windows.
v By editing copies of sample files.
Read these topics for information on configuring your CICS Transaction
Gateway:
“Editing the sample configuration files” How to configure the CICS Transaction
Gateway by copying and editing sample
configuration files.
“Setting environment variables” on
page 47
How to set environment variables, for
example, to control the use of EXCI pipes,
and the names of CICS servers that callers
can access.
“Using the configuration tool” on page 52 How to configure the CICS Transaction
Gateway by using the configuration tool.
“Other configuration tasks:” on page 73 Contains information about other tasks
you have to do to configure the CICS
Transaction Gateway.
“Configuring CICS Transaction Gateway
for use with RACF ® ” on page 65
Read this if your CICS Transaction
Gateway will use RACF.
See also these sources of information:
v IBM Redbooks (see “Redbooks” on page 167)
v Chapter 4, “Configuring the CICS Transaction Server for z/OS” on page 37
Editing the sample configuration files
To configure the CICS Transaction Gateway, you create two files: ctgenvvar
and CTG.INI. Sample files are provided in the /bin directory:
© Copyright IBM Corp. 1996, 2002 43

Configuration
Sample version
()
Working version
()
Used by
ctgenvvarsamp ctgenvvar All applications that use the
CICS Transaction Gateway to
communicate with CICS in local
mode.
CTGSAMP.INI CTG.INI The CICS Transaction Gateway
only.
Note: The filenames are case-sensitive.
To create working versions, copy the to
/bin/, and then edit the new file. Do the
following for both ctgenvvarsamp and CTGSAMP.INI:
From Telnet or OMVS
To copy the file, issue these commands:
cd /bin
cp
To edit the new file, issue one of the following commands:
On Telnet:
vi
On OMVS:
oedit
From TSO ISHELL
To copy the file:
1. Set the pathname to /bin/
2. Issue the N command.
3. Set the following in the Create a New File dialog box:
Permissions :755
File Type :2 (Regular file)
File source for regular file:2 (Copy file)
4. In the Replace a File dialog box accept the source as 1 (File).
5. Type the following on the Enter the Pathname dialog box:
/bin/
6. Set the file permissions to 755 in the dialog box that opens.
To edit the new file:
1. Leave the pathname as /bin/
2. Issue the command E (Edit).
44 CICS Transaction Gateway: z/OS Administration

Note: Some lines of the INI file are longer than 72 characters; take care when
editing them.
In the following sections relevant settings for each file are shown, together
with their corresponding definition in “Using the configuration tool” on
page 52.
General Gateway settings in CTG.INI
Entry in CTG.INI Corresponding field in the configuration
tool
closetimeout “Timeout for in-progress requests to
complete (ms)” on page 58
connectionlogging “Log client connections and
disconnections” on page 58
ecigenericreplies “Let Java clients obtain generic ECI
replies” on page 58
initconnect “Initial number of Connection Manager
threads” on page 56
initworker “Initial number of Worker threads” on
page 56
maxconnect “Maximum number of Connection
Manager threads” on page 56
maxworker “Maximum number of Worker threads”
on page 57
noinput “Enable reading input from console” on
page 57
nonames “Display TCP/IP hostnames” on page 57
notime (No equivalent field)
uowvalidation “Validate Units of Work” on page 58
workertimeout “Worker thread available timeout (ms)”
on page 58
Protocol settings
Protocol settings take this form:
protocol@tcp.handler=com.ibm.ctg.server.TCPHandler
protocol@tcp.parameters=connecttimeout=2000;idletimeout=600000;...
Figure 10. Extract from TCP protocol entry in CTG.INI
Configuration
A protocol is enabled if an entry for it exists in the CTG.INI file. Entries for
each protocol must be in the form shown:
Chapter 5. Configuring the CICS Transaction Gateway 45

Configuration
v Two lines are allowed for each protocol. 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:
protocol@tcp.parameters=connecttimeout=2000;\
idletimeout=600000;
v The first line defines the protocol.
v The second line defines the parameters.
v Parameters are separated by a semicolon.
The following table shows how parameters in the CTG.INI file map to fields in
the configuration tool:
Entry in CTG.INI Equivalent field in the configuration
tool
allowaddr Authorized Hosts. If specifying more than
one host, the format of the entry is as
follows:
allowaddr=host1;\
allowaddr=host2;
clientauth Use client authentication
connecttimeout Connection timeout (ms)
dropworking Drop working connections
idletimeout Idle timeout (ms)
keyring KeyRing database (System SSL,
System HTTPS)
KeyRing or Keystore name (SSL,
keyringpw KeyRing or Keystore password
keyringpwscrambled (No equivalent)
maxconn Maximum dedicated connections
pingfrequency Ping time frequency (ms)
port Port
requiresecurity Require clients to use security classes
solinger SO_LINGER setting
sotimeout Handler wakeup timeout (ms)
Summary of environment variables
Table 6 on page 47 shows how the environment variables relate to the
configuration tool settings (see “Configuring CICS Transaction Gateway
settings” on page 56) and the variables contained in the ctgenvvar script.
46 CICS Transaction Gateway: z/OS Administration

Table 6. Environment variables
Environment variable ctgenvvar environment variables configuration tool setting
AUTH_USERID_PASSWORD AUTH_USERID_PASSWORD Use RACF Authentication
CICSCLI - (defaults to CTG.INI in the
current directory from where the
Gateway is run — normally
ctg/bin)
-
CLASSPATH Concatenation of: CLASSPATH,
CTG_USER_CLASSPATH,
CTG_CLASSPATH
CTG User Classpath
CTG_RRMNAME RRMNAME RRM Name
DFHJVPIPE DFHJVPIPE EXCI Net Name
DFHJVSYSTEM_nn DFHJVSYSTEM_nn CICS Server, CICS Description
LD_LIBRARY_PATH Concatenation of:
LD_LIBRARY_PATH,
CTG_USER_LIBPATH,
CTG_LIBPATH
CTG User Libpath
LIBPATH Concatenation of:
CTG_USER_LIBPATH,
CTG_LIBPATH, and current
LIBPATH
STEPLIB Concatenation of: STEPLIB,
EXCI_OPTIONS, EXCI_LOADLIB
CTG User Libpath
Configuration
EXCI Load Library (High Level
Qualifier, Library Name), EXCI
Options
Setting environment variables
Environment variables control how the CICS Transaction Gateway functions.
Use the ctgenvvar script to set environment variables for CICS Transaction
Gateway for z/OS. The ctgenvvar script can be executed alone or referenced
by the ctgstart script to set the variables.
You can create the ctgenvvar script in two ways:
v By using the configuration tool to define the environment settings and to
create the ctgenvvar script; see “z/OS Environment settings” on page 64.
This is the recommended way if you have X-Windows.
The values in the ctgenvvarsamp are loaded as defaults.
v By editing the supplied ctgenvvarsamp script, and then copying or
renaming to ctgenvvar script, see “Editing the sample configuration files”
on page 43.
Chapter 5. Configuring the CICS Transaction Gateway 47

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Configuration
If a ctgenvvar script is not found when ctgstart runs, settings for the
environment variables in the ctgstart script itself are used.
You can also set the environment variables by:
v Entering commands on an z/OS UNIX System Services command line. For
example, the following command sets the DFHJVPIPE environment variable
to use a specific pipe called JAVAGAT1.
export DFHJVPIPE=JAVAGAT1
If the value of an environment variable contains spaces, enclose it in single
or double quotes. For example:
export DFHJVSYSTEM_00="MYCICS-Test CICS system"
v By creating a JCL job that includes environment variable settings to start
the gateway. See “Starting with JCL” on page 121. If you set environment
variables in the ctgenvvar or ctgstart script, these override settings in the
JCL.
All CICS regions refer to the same instance of a variable except
DFHJVSYSTEM_nn which is unique to the region. This consists of the server
name and description.
After you have installed the product, you can use ctgenvvar to establish the
environment that Java applications running in local mode will use, for
example:
./bin/ctgenvvar
Because ctgenvvar searches for ctgstart, ensure that /bin is
in the path for the current environment.
The environment variables
You can export the following environment variables for CICS Transaction
Gateway. Refer to Table 6 on page 47 for details of how these relate to
configuration tool and ctgenvvar settings.
AUTH_USERID_PASSWORD
Specifies whether the user ID and password is authenticated with
RACF.
If you set AUTH_USERID_PASSWORD to Yes you must also set
_BPX_SHAREAS to Yes, and JAVA_PROPAGATE to NO. If you set
AUTH_USERID_PASSWORD through the Use RACF Authentication
check box in the configuration tool, file ctgenvvar is updated for you.
If you set this variable see also “Configuring CICS Transaction
Gateway for use with RACF ® ” on page 65.
CICSCLI
48 CICS Transaction Gateway: z/OS Administration

|
|
You can specify a different path to the configuration file by setting the
CICSCLI environment variable. (The CICS Transaction Gateway log
indicates the location of CTG.INI.) The CICS Transaction Gateway will
not run if a configuration file is not found.
CLASSPATH
Includes the path in HFS for the CICS-provided Java jar files, that is,
/ctg/classes. You must set CLASSPATH to compile and run Java
applications.
CTG_RRMNAME
The name of the resource manager managing this instance of the CICS
Transaction Gateway. For Resource Recovery Services, the name must
be unique across a sysplex.
The name can consist of the following printable characters:
1. Alphanumeric characters: A-Z and 0-9
2. National characters: $ (X'5B'), # (X'7B'), @ (X'7C')
3. The period (.)
4. The underscore (_)
The name cannot start with a blank or contain embedded blanks.
Lower case characters are converted to upper case characters.
The name must end with these characters:
.IBM.UA
Configuration
To avoid naming conflicts, use A-C or G-I as the first character.
The length of CTG_RRMNAME must not exceed 32 characters.
DFHJVPIPE
The name of the specific pipe that the CICS Transaction Gateway is to
use for EXCI calls. If this variable is not set, the CICS Transaction
Gateway uses a generic pipe.
DFHJVSYSTEM_nn
You may set up to 100 environment variables of the form
DFHJVSYSTEM_nn, where nn ranges from 00 to 99. The first variable
must be DFHJVSYSTEM_00, and subsequent variables must have
consecutive numbers, or they will not be recognized. The value of the
variable is the name and description of a CICS system to be returned
in response to a request for the CICS_EciListSystems function.
The value is a string containing the uppercase APPLID of the CICS
system, followed by a hyphen (-), followed by a description of the
CICS system. The description may not be more than 60 bytes long.
For example if you specify:
Chapter 5. Configuring the CICS Transaction Gateway 49

|
|
|
|
|
Configuration
DFHJVSYSTEM_00="MYCICS-Test CICS system"
CICS_EciListSystems returns details of a CICS system called MYCICS
with description Test CICS system.
LD_LIBRARY_PATH
Includes the path in HFS for the CICS Transaction Gateway executable
code. Set it to /ctg/bin.
LIBPATH
This is the path in HFS for the CICS Transaction Gateway executable
code. It is a concatenation of the LD_LIBRARY_PATH and any other
existing libraries in LIBPATH. Ensure that as a minimum it is set to
/ctg/bin, the same as LD_LIBRARY_PATH.
STEPLIB
The library containing the default EXCI options and the EXCI load
modules. STEPLIB is a concatenation of the EXCI_OPTIONS and
EXCI_LOADLIB variables. EXCI_OPTIONS references the data set that
contains the EXCI options table DFHXCOPT. The default supplied
table is contained in SDFHEXCI. EXCI_LOADLIB should reference the
SDFHEXCI and SDFHLOAD libraries.
Customizing EXCI options
The EXCI options table, DFHXCOPT, allows you to specify a number of
parameters for the EXCI. There is no suffixed version of this program, so the
first DFHXCOPT table located in the STEPLIB concatenation is loaded.
Figure 11 shows the default parameters for the DFHXCOPT macro.
DFHXCO TYPE=CSECT,
TIMEOUT=0, No timeout
TRACE=OFF, Only Exception trace entries
TRACESZE=16, 16K trace table
DURETRY=30, Retry SDUMPS for 30 seconds
TRAP=OFF, DFHXCTRA - OFF
GTF=OFF, GTF - OFF
MSGCASE=MIXED, Mixed case messages
CICSSVC=0, EXCI will obtain CICS SVC number
CONFDATA=SHOW, Show user commarea data in trace
SURROGCHK=YES Perform surrogate-user check @P1C
END DFHXCOPT
Figure 11. EXCI options table DFHXCOPT
For full details see the CICS External Interfaces Guide. The relevant parameters
(shown in bold in Figure 11) are:
TRACE
The default value OFF means that EXCI tracing is not required. Exception
trace entries are always written to the internal trace table.
50 CICS Transaction Gateway: z/OS Administration

Configuration
GTF
If you want to copy entries in the EXCI trace table to the generalized trace
facility (GTF), specify GTF=ON.
CICSSVC
This specifies the CICS type 3 SVC number being used for MRO
communication. EXCI must use the same SVC number that is used by the
CICS MRO regions that reside in the MVS image where the client
program is running. If you do not specify a specific CICS SVC number,
the external CICS interface determines the SVC in use for MRO by means
of an MVS VERIFY command.
The default value zero means that EXCI will get the CICS SVC number
from MVS. Specify 0 only when you are sure that at least one CICS region
has logged on to DFHIRP during the life of the MVS IPL. If you use the
default, and the external CICS interface requests the SVC from MVS, the
request will fail if no CICS region has logged on to DFHIRP.
In other circumstances, specify the CICS SVC number, in the range
200–255, that is in use for CICS interregion communications. This must be
the SVC number that is installed in the MVS image in which the client
program is running (the local MVS).
Note: All CICS regions using MRO within the same MVS image must use
the highest level of both DFHIRP and the CICS SVC, DFHCSVC. If
your MRO CICSplex consists of CICS regions at different release
levels, the DFHIRP and DFHCSVC installed in the LPA must be
from highest release level of CICS within the CICSplex.
CONFDATA
The default value SHOW allows user data to be traced. If you wish to
hide it, set this value to HIDETC.
SURROGCHK
The default value YES means that a surrogate security check will be
performed in the EXCI client address space if the flowed user ID is
different from the user ID of the client address space. This occurs
regardless of the CICS security settings. This means that if you flow a
user ID in an EXCI request (including flowing a user ID with an External
Call Interface [ECI] request using the CICS Transaction Gateway for
z/OS), you need either to add an RACF surrogate profile, or disable
surrogate security checks by setting this parameter to NO.
Note: If the CICS region has no security (SEC=NO), specify
SURROGCHK=NO. For more information, refer to the CICS RACF
Security Guide.
Chapter 5. Configuring the CICS Transaction Gateway 51

|
|
|
Configuration
Referencing your customized EXCI options
If you customized the EXCI options in DFHXCOPT, update the
EXCI_OPTIONS environment variable to specify the library that contains the
customized options table. You can do this either by:
v Using the configuration tool to set EXCI Options; see “z/OS Environment
settings” on page 64.
v Editing the ctgenvvar script. Find the line:
EXCI_OPTIONS="your.user.loadlib"
and change it to specify the appropriate library.
For more information about the EXCI options and how to customize them, see
the CICS External Interfaces Guide.
You must update the name of the library specified in the EXCI_LOADLIB
environment variable. This library contains:
v The default EXCI options.
v The EXCI load modules.
You can update EXCI_LOADLIB by:
v Using the configuration tool to set High Level Qualifier and Library
Name, see “z/OS Environment settings” on page 64.
v Editing the ctgenvvar script. Find the line:
EXCI_LOADLIB="CICSTS22.CICS.SDFHEXCI"
and change it to specify the appropriate library and high-level qualifier.
The EXCI_OPTIONS and EXCI_LOADLIB variables are used in the definition
of the STEPLIB environment variable.
Using the configuration tool
Use the configuration tool to set configuration parameters for the CICS
Transaction Gateway.
To use the configuration tool, export the display using the commands
described in “Using X-Windows from a remote system” on page 34.
To start the configuration tool, enter the ctgcfg command.
The configuration is stored by default in the CTG.INI file in the
/bin subdirectory. You can edit this file directly, if you find
this preferable to using the configuration tool. If a configuration file already
exists when you start the configuration tool, the settings in the file are loaded
into the configuration tool.
52 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
You can specify a different path to the configuration file by setting the
CICSCLI environment variable. (The CICS Transaction Gateway log indicates
the location of CTG.INI.) The CICS Transaction Gateway will not run if a
configuration file is not found.
You must restart the CICS Transaction Gateway for any changes to the
configuration file to take effect.
Running the configuration tool on a different operating system
You can use the configuration tool on any of the other CICS Transaction
Gateway operating systems to generate a configuration file for your operating
system. See Appendix A, “Hardware and software” on page 155 for other
supported operating systems.
1. Install CICS Transaction Gateway on the workstation on which you want
to run the configuration tool.
2. To edit an existing configuration, copy CTG.INI, and ctgenvvar, tothe
/bin subdirectory on the workstation, using FTP in ASCII
mode.
3. Issue the following command:
ctgcfg -PLAT ZOS
This makes the configuration tool run as if it is on your operating system.
4. Make the required entries and click Save. This creates or updates the
CTG.INI file and the ctgenvvar file.
5. Use FTP in ASCII mode to transfer the files to your system. Ensure that
the z/OS ftp agent is using the same code page as the CICS Transaction
Gateway will use; see Appendix B, “Supported code pages” on page 163
for supported code pages.
The configuration tool interface
The screen has four input areas (described separately below):
1. Menu bar
2. Toolbar
3. Tree structure
4. Settings panel
Using the configuration tool
A fifth area, the status bar, shows which configuration file and operating
system you are using. The status bar is display only.
Chapter 5. Configuring the CICS Transaction Gateway 53

|
|
|
|
Using the configuration tool
Figure 12. The configuration tool
Tree structure
The tree structure (see Figure 12) allows you to navigate through all of the
settings in your configuration. The types of root node are as follows:
Java Gateway Contains a subnode for each protocol that the CICS
Transaction Gateway can use (TCP, SystemSSL, SSL, HTTP,
SystemHTTPS, HTTPS and TCPAdmin).
EXCI Client Contains a subnode for each of your server definitions.
Menu bar
The menu bar contains the File, Edit, Tools, Settings, and Help pulldowns.
The File pulldown has the following options:
New Creates a new configuration.
Open Opens an existing configuration.
Save Saves the current configuration. If a new configuration has
been created, the file name is CTG.INI (in the
/bin subdirectory).
54 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
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 pulldown has Cut, Copy and Paste options, which perform the
standard text functions.
The Tools pulldown has the following options:
Trace Settings Displays the Trace Settings dialog.
New Server Defines a new server named New Serv.
Delete Server Deletes a server node from the tree structure.
Using the configuration tool
The Settings pulldown 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.
Any changes that you make to color and font settings are lost when you close
the configuration tool.
The Help pulldown has the following options:
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” on page 169.
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.
Chapter 5. Configuring the CICS Transaction Gateway 55

|
|
|
|
|
|
|
|
Using the configuration tool
Settings panels
When you select nodes in the tree structure, the relevant settings panel is
displayed. The settings in these panels correspond to parameters in the
CTG.INI and ctgenvvar files.
On each settings panel there is an Undo Changes button that allows you to
undo changes you have made.
Configuring CICS Transaction Gateway settings
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 defined using the configuration tool is specified via the
associated command line option when the Gateway is started, the command
line setting takes precedence.
General Gateway settings
The general Gateway settings are:
Initial number of Connection Manager threads: Enter the initial number of
ConnectionManager threads. The default is 1.
Set this to the normal number of JavaGateway objects opened by all
connected Java clients.
You can override this setting with the ctgstart -initconnect command.
Maximum number of Connection Manager threads: Enter the maximum
number of ConnectionManager threads. The default is 100.
This limits the maximum number of JavaGateway objects opened by all
connected Java clients. Set this to the maximum number of JavaGateway
objects that could be open at any one time from all the remotely-connected
Java clients.
You can override this setting with the ctgstart -maxconnect command.
If you select the Unrestricted checkbox, no limits are applied to the number of
ConnectionManager threads.
For information on threading limits, see Table 3 on page 15.
Initial number of Worker threads: Enter the initial number of Worker
threads. The default is 1.
Set this to the normal number of concurrent requests expected to be processed
concurrently by the CICS Transaction Gateway daemon.
56 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
You can override this setting with the ctgstart -initworker command.
Maximum number of Worker threads: Enter the maximum number of
Worker threads. The default is 100.
This limits the maximum number of parallel ECI requests that the CICS
Transaction Gateway can process. Set it to:
v Less than or equal to maxconnect (for single JavaGateway programs)
v Less than or equal to the RECEIVECOUNT set in the CICS sessions
definition
v Less than or equal to 100 since this is the maximum number of EXCI pipes
that a z/OS address space can allocate
As there is a limit of 100 pipes per MVS address space, it is recommended
that you set the Maximum number of Worker threads to (100 divided by the
number of unique applids in communication with the CICS Transaction
Gateway). This is because a pipe is allocated per thread per applid. See “EXCI
pipe limitations” on page 142 for more information. To increase throughput,
consider starting multiple instances of the CICS Transaction Gateway (see
“Starting multiple CICS Transaction Gateways” on page 124).
If you select the Unrestricted checkbox, no limits are applied to the number of
Worker threads.
You can override this setting with the ctgstart -maxworker command.
For information on threading limits, see Table 3 on page 15.
Enable reading input from console: Select this check box to enable the
reading of input from the console.
Reading of input from the console is enabled by default.
Using the configuration tool
You can override this setting with the ctgstart -noinput command.
Display TCP/IP hostnames: Select this check box to enable the display of
TCP/IP hostnames 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 hostnames in messages. This makes the
messages easier to read.
Chapter 5. Configuring the CICS Transaction Gateway 57

|
|
|
|
|
|
|
|
|
|
|
|
|
Using the configuration tool
Note: Selecting this option might cause severe performance reduction on
some systems.
Let Java clients obtain generic ECI replies: Select this check box if you wish
Java clients 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.
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.
Log 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
client application program connects to, or disconnects from, the Gateway
daemon. The default is for these messages not to be written.
Timeout for in-progress requests to complete (ms): Enter a value in
milliseconds.
When a Java-client program disconnects from the Gateway, the Gateway may
still be processing requests on behalf of that program. If work is still in
progress, the ConnectionManager that was managing requests on behalf of
that Java-client waits for the requests to complete for up to the timeout
period. If there are still requests in progress after the timeout has expired, the
ConnectionManager continues its processing and marks itself as available for
use by a new connection. The default timeout is 10 000 milliseconds, but you
may enter a value to override the default.
If this value is set to zero, the ConnectionManager does not wait for
in-progress requests to complete.
Worker thread available timeout (ms): Enter a value in milliseconds.
When a ConnectionManager accepts a request, it must allocate a Worker
thread to execute that request. If a Worker does not become available within
58 CICS Transaction Gateway: z/OS Administration

the 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 is
immediately available.
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.
Port: Enter the TCP/IP port number.
The default port for TCP/IP is 2006.
You can override this setting with the ctgstart -port command.
Handler wakeup timeout (ms): Enter a value in milliseconds.
This setting controls how frequently the protocol handler wakes from
accepting inbound connections. When it wakes, it checks to see whether the
Gateway is being stopped, and so this value affects the time taken for the
Gateway to shutdown cleanly. If you set this value to zero then the handler
only wakes when a new connection is accepted, and so the Gateway will not
shutdown cleanly until that time.
Connection timeout (ms): Enter a value in milliseconds.
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,
then the connection is refused. If this value is set to zero, a connection is
refused if a ConnectionManager is not immediately available.
Idle timeout (ms): Enter a value in milliseconds.
Using the configuration tool
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 connection is
disconnected, though if work is still in progress on behalf of the connection, it
may be left connected. If this value is not set, or is set to zero, then idle
connections will not be disconnected.
Cleanup processing will only result after a timeout if the server has support
for this function installed.
Chapter 5. Configuring the CICS Transaction Gateway 59

Using the configuration tool
Ping time frequency (ms): Enter a value in milliseconds.
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 PONG response has not
been received by the time the next PING message is due to be sent, then the
connection is disconnected. Again, if work is still in progress on behalf of the
connection it may (depending on the drop working connections value setting)
be left connected. If this value is not set, or is set to zero, then PING messages
are not sent.
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.
SO_LINGER setting: Enter a SO_LINGER setting for any socket used by this
handler. The SO_LINGER setting specifies a delay value in seconds for closing
a socket. If this value is not entered, or set to zero, then SO_LINGER is
disabled for any sockets used by this protocol handler.
If SO_LINGER is enabled, and data transmission has not finished, a Close call
blocks the calling program until the data is transmitted or until the connection
times out. If SO_LINGER is disabled, a Close call 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.
Require clients to use security classes: Select this check box if you wish
your Gateway to accept only connections that use security classes.
When a Java-client program 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.
System SSL protocol settings
Select the System SSL subnode to display the settings for System SSL. The
settings are the same as for TCP except that 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.
60 CICS Transaction Gateway: z/OS Administration

When client authentication is enabled, any connection attempted to either the
ssl: or https: 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
“Configuring your SSL clients” on page 80.
KeyRing database: Enter the database file name (.kdb) of the server
KeyRing.
The server KeyRing should consist of a valid x.509 certificate that is used to
identify this server to connecting clients. This KeyRing database is generated
using the System SSL tool (GSKKYMAN).
For more information about SSL and its associated KeyRing databases, see
Chapter 6, “Network Security” on page 75.
KeyRing or Keystore password: Enter the password that you specified for
the server KeyRing or KeyStore.
CICS Transaction Gateway writes the password to the configuration file in a
form that prevents a casual observer from easily reading it.
The default port for System SSL is 8050.
Using the configuration tool
SSL protocol settings
Select the SSL subnode to display the settings for JSSE or SSLight. The
settings are the same as for System SSL except for the following setting, which
is used instead of KeyRing database.
KeyRing or Keystore name: Enter the server KeyRing classname for SSLight,
or the server KeyStore name for JSSE.
For a KeyStore, 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:
/mykeys/jsse/keystore.jks
\\mykeys\\jsse\\keystore.jks
The server KeyRing or KeyStore consists of a valid x.509 certificate that
identifies this server to connecting clients. This KeyRing or KeyStore is
generated using the SSL tools supplied with this product.
For more information about SSL and its associated KeyRings or KeyStores, see
Chapter 6, “Network Security” on page 75.
Chapter 5. Configuring the CICS Transaction Gateway 61

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using the configuration tool
The default port for SSL is 8050.
HTTP protocol settings
Select the HTTP subnode to display the settings for HTTP. The settings are
the same as for TCP.
The default port for HTTP is 8080.
System SSL HTTPS protocol settings
Select the System SSL HTTPS subnode to display the settings for HTTPS
over System SSL. The settings are the same as for HTTP except that System
SSL HTTPS also has Use client authentication, KeyRing database, and
KeyRing or Keystore password settings.
The default port for HTTPS is 443.
TCPAdmin protocol settings
Select the TCPAdmin subnode to display the settings for administration. The
settings are the same as for TCP except for the following:
v The default port is 2810
v There is no Require clients to use security classes field.
v TCPAdmin also has the following settings:
Max dedicated connections: Enter a value specifying the maximum number
of simultaneous dedicated client connections that can be made to the Gateway
administration handler.
Authorized Hosts: Enter a host name or IP address in the entry field. Click
Add to add the host to the Authorized Hosts list, below the entry field. Click
Remove to remove all selected hosts from the Authorized Hosts list.
If there are entries in the Authorized Hosts list, only those hosts are allowed
to access the administration protocol handler. Be aware: If the list is empty, all
hosts are allowed access.
The default entry is 127.0.0.1, which represents the host on which the CICS
Transaction Gateway is installed. IP address 127.0.0.1 and the host name
localhost are considered to be different from the real IP address or host name
of the system.
For information about administering your system, see “Administering your
system” on page 128.
62 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HTTPS protocol settings
Select the HTTPS subnode to display the settings for HTTPS over JSSE or
SSLight. The settings are the same as for HTTP except that HTTPS also has
Use client authentication, KeyRing or Keystore name, and KeyRing or
Keystore password settings.
The default port for HTTPS is 443. However, on some operating systems,
processes require special privileges to access port numbers between 1 and
1024. If you plan to run CICS Transaction Gateway without these required
privileges, change the port number to a value greater than 1024.
Trace settings
To configure the trace settings, select the Trace settings option from the Tools
menu.
Gateway: Select this checkbox to enable tracing of the CICS Transaction
Gateway.
This is equivalent to specifying the -trace option on the ctgstart command.
JNI trace: You cannot enable JNI trace through the configuration tool. Use
one of the following methods to enable it:
v When you start the CICS Transaction Gateway, issue the command
ctgstart -j-Dgateway.T.setJNITFile=filename
Using the configuration tool
where filename is the name of the file to which trace output is to be sent.
v While the CICS Transaction Gateway is running, use the system
administration functions. You must have enabled the TCPAdmin protocol
handler (see “TCPAdmin protocol settings” on page 62). See “Administering
your system” on page 128 for details of how to enable JNI trace
dynamically.
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
Using the CTG_JNI_TRACE environment variable to enable JNI trace is
supported only for migration purposes.
Chapter 5. Configuring the CICS Transaction Gateway 63

|
Using the configuration tool
Gateway trace file: Enter the pathname of a trace file to which trace
messages will be written, if tracing is enabled. If no path is specified, the trace
is written as follows:
/bin/ctg.trc
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.
Gateway trace wrap size: Enter a value in the range 0 through 1 000 000
kilobytes.
This value specifies the size in kilobytes to which the gateway trace file will
grow. Subsequent trace entries will continue to be written from the beginning
of the file. The default value of 0 disables wrapping.
z/OS Server settings
To configure a new CICS Server, select New Server from the Tools menu, or
from the toolbar.
You can define a maximum of 100 servers.
CICS Server: Enter a name of between 1 and 8 characters. This is the name
of a CICS system that is returned in response to a request for the
CICS_EciListSystems function.
CICS Description: Enter a description of between 1 and 60 characters. This
is the description of a CICS system that is returned in response to a request
for the CICS_EciListSystems function.
z/OS Environment settings
To configure the z/OS environment settings, select a CICS Server node.
For more information about the environment variables associated with these
settings, refer to “Setting environment variables” on page 47.
Use RACF Authentication: Select this check box to specify that the userid
and password passed on an EXCI call should be authenticated with RACF. If
you select this option, refer to the “Configuring CICS Transaction Gateway for
64 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
use with RACF ® ” for further information about tasks to be completed when
authentication is required.
High Level Qualifier: Enter the high level qualifier for the library that
contains the default EXCI load modules. The default is CICSTS22.CICS.
Library Name: Enter the name of the library that contains the default EXCI
load modules. The default is SDFHEXCI.
RRM Name: Enter the name of the resource manager that is managing this
instance of the CICS Transaction Gateway for z/OS. The maximum length of
this name is 32 characters. For Resource Recovery services, the name must be
unique across a sysplex.
Important: To avoid naming conflicts, you should use A-C or G-I as the first
character.
EXCI Options: Enter the name of the library containing the default EXCI
options.
CTG User Classpath: Enter a pathname to be added to the current
CLASSPATH environment setting. Note that the configuration tool
automatically sets the path for ctgclient.jar, ctgserver.jar, and cfwk.zip.
CTG User Libpath: Enter a pathname to be added to the current LIBPATH
environment setting. Note that the configuration tool automatically sets the
path for the location of ctgstart.
EXCI Net Name: Enter name of the specific pipe that the CICS Transaction
Gateway is to use for EXCI calls. If you do not specify a specific pipe, the
CICS Transaction Gateway uses a generic pipe.
Configuring CICS Transaction Gateway for use with RACF ®
Using the configuration tool
CICS Transaction Gateway provides support for user ID and password
authentication with RACF, together with the option to map a registered X.509
certificate to a RACF user ID (see “Mapping client certificates to RACF
userids” on page 105). Both of these features use the z/OS UNIX C/C++
pthread_security_np function to call RACF.
Preliminary checks
In the instructions that follow, you will use the extattr +p command to
mark HFS files as program controlled. To use this command, you must be
the owner of the files, or a superuser. The user ID that installed the CICS
Transaction Gateway normally owns the files. You also need READ access
to the BPX.FILEATTR.PROGCTL FACILITY class. See OS/390 UNIX System
Services Planning for more information. Your user id must have the RACF
Chapter 5. Configuring the CICS Transaction Gateway 65

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using the configuration tool
SPECIAL attribute to perform the actions in step 3. Follow these steps to
check that you have the necessary authority:
1. Log on to MVS.
2. Run ISPF.
3. Choose option 6 (Command).
4. Issue the following command:
SR CLASS(FACILITY)
Check that these entries are in the list that appears:
BPX.SERVER
BPX.FILEATTR.PROGCTL
5. Issue the following command:
SR CLASS(SURROGAT)
Check that this entry is in the list that appears:
*.DFHEXCI
Configuring the system
1. Mark the load modules used by the CICS Transaction Gateway as
program controlled. Use these commands from an OMVS or Telnet
screen:
extattr +p /bin/lib*.so
extattr +p /bin/SECURES
2. If necessary, activate program control by issuing these commands:
SETROPTS CLASSACT(PROGRAM)
RDEFINE PROGRAM * UACC(READ)
SETROPTS WHEN(PROGRAM)
3. Mark as program controlled the CICS SDFHEXCI library, which
provides the EXCI for the CICS Transaction Gateway. For example, if
this library was installed as CICSTS22.CICS.SDFHEXCI, use the
following RACF command:
RALTER PROGRAM *ADDMEM(’CICSTS22.CICS.SDFHEXCI’//NOPADCHK)
SETROPTS WHEN(PROGRAM)REFRESH
4. Specify that the ctgstart script does not share its address space with
any other processes, to ensure that the calling address space (JVM) is
not contaminated by a non-program-controlled load module. Enter:
extattr -s /bin/ctgstart
5. If the CICS Transaction Gateway is configured to use System SSL,
mark as program controlled the binaries and data sets provided by
this separate product. See “System SSL” on page 95 for information
about System SSL. The CICS Transaction Gateway is not configured to
use System SSL by default. If your system has been configured for this
protocol, an entry similar to this appears in CTG.INI:
66 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
protocol@systemssl_ssl.handler=com.ibm.ctg.server.GskSslHandler
Issue commands like the following:
extattr +p /usr/lpp/gskssl/lib/*
extattr +p /usr/lpp/gskssl/bin/*
Also mark as program controlled any .kdb keyring files generated
using System SSL, that the CICS Transaction Gateway uses.
6. Give the user ID under which the CICS Transaction Gateway runs
READ access to the BPX.SERVER FACILITY profile. For more
information, see the __passwd() section in OS/390 V2R10.0 C/C++
Run-Time Library Reference, (SC28-1663-08).
7. Give the user ID under which the CICS Transaction Gateway runs
READ access to the RACF profile that protects the
TCPIP.STANDARD.TCPXLBIN data set. This contains tables for
translating from ASCII to EBCDIC and from EBCDIC to ASCII.
8. Use one of the following options to configure the CICS Transaction
Gateway:
Editing ctgenvvar
Ensure that these entries appear in the file:
export AUTH_USERID_PASSWORD=Yes
export _BPX_SHAREAS=Yes
export JAVA_PROPAGATE=No
Using the configuration tool
Select the Use RACF Authentication option in the Environment
Settings panel; see “z/OS Environment settings” on page 64.
Problems
If you have problems after configuring your system as described above, see
“ECI_ERR_SECURITY_ERROR return code” on page 147.
J2EE setup and configuration
Using the configuration tool
This topic discusses the administration of CICS resource adapters. Two
resource adapters are supplied with the CICS Transaction Gateway. The
/deployable directory contains two resource adapter files:
cicseciRRS.rar
v This requires WebSphere Application Server for z/OS v4.01 with PTF
UQ99329 (Service Level W401030).
Chapter 5. Configuring the CICS Transaction Gateway 67

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using the configuration tool
v It contains J2EE CICS ECI connector support that is designed
specifically to work with the resource recovery (RRS) component of
z/OS or OS/390, so that applications can benefit from two-phase
commit capability for transactions.
v It must be run in the WebSphere Application Server v4.0 Runtime
environment, not the WebSphere Application Server v4.0 plugin
environment.
v It can be deployed only in CICS Transaction Gateway local mode.
v The getLocalTransaction method of the ECIConnection class is not
supported.
v The interaction types SYNC_SEND and SYNC_RECEIVE are not
supported.
cicseci.rar
v This is designed for use with all J2EE servers, other than WebSphere
Application Server for z/OS, which support the J2EE Connector
Architecture version 1.0.
v Do not use this rar file with WebSphere Application Server for z/OS v4.
Any value set by the setExecuteTimeout method of the ECIInteractionSpec
class is ignored; neither connector supports timeout. An alternative is to set
the TIMEOUT parameter in the external CICS interface options table,
DFHXCOPT. See the CICS External Interfaces Guide for more information.
Deploying CICS resource adapters
Before you can use a J2EE resource adapter in a server runtime environment
you must supply parameters for its internal ManagedConnectionFactory class.
In a managed environment you set these parameters when you deploy the
resource adapter to your server. For instructions on how to do this consult
your server’s documentation.
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 both the
cicseci and cicseciRRS resource adapters, and their effect on the final deployed
resource adapter. The tools used to configure these parameters are
server-specific. Not all parameters are required; the default value is shown
where appropriate.
ConnectionURL
The URL of the CICS Transaction Gateway with which the resource
68 CICS Transaction Gateway: z/OS Administration

Deployment parameters for the ECI resource adapters
adapter will communicate. The URL takes the form
protocol://address. These protocols are available:
v tcp
v http
v ssl
v local
So, for example, you might specify a URL of tcp://ctg.business.com.
For the local protocol simply specify local:.
For the cicseciRRS resource adapter, only the local protocol is valid.
PortNumber
The port to connect to where the CICS Transaction Gateway is
running. This parameter is not relevant if you are using the local
protocol.
This parameter is not valid for the cicseciRRS resource adapter,
because it operates only in local mode.
ServerName
The name of the CICS server to connect to for all interactions through
this resource adapter. This is the name as defined in the CICS
Transaction Gateway configuration file. To use multiple servers within
an environment you must deploy several resource adapters, each with
a different ServerName attribute set.
TranName
The name of the CICS Transaction under which you want all
programs started by the resource adapter to run.
TPNName
The name of the CICS TPN Transaction under which you want all
programs started by the resource adapter to run. Note that TPNName
takes precedence if both TranName and TPNName are specified.
UserName
The CICS userid to be used if no other security credentials are
available. See the J2EE section in the CICS Transaction Gateway:
Programming Guide for more information.
Password
The password for the CICS userid 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
then no ClientSecurity class is used. For more information on what
ClientSecurity classes are used for, and how to write them, see CICS
Chapter 5. Configuring the CICS Transaction Gateway 69

Deployment parameters for the ECI resource adapters
Transaction Gateway security classes in the Java chapter of the CICS
Transaction Gateway Programming Guide.
This parameter is not valid for the cicseciRRS resource adapter,
because it operates only in local mode.
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
then 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.
This parameter is not valid for the cicseciRRS resource adapter,
because it operates only in local mode.
KeyRingClass
The fully qualified name of the SSL keyring class to use. This only
applies when using the SSL protocol.
This parameter is not valid for the cicseciRRS resource adapter,
because it operates only in local mode.
KeyRingPassword
The password for the class defined in KeyRingClass. Because it is
linked to KeyRingClass, it is also optional, and applies only to the SSL
protocol.
This parameter is not valid for the cicseciRRS resource adapter,
because it operates only in local mode.
TraceLevel
The level of trace to be output by the resource adapter. For more
details on trace levels and tracing see “Tracing” on page 71.
As well as these user-definable properties, the cicseci 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 cicseci resource adapter is defined as LocalTransaction. If your
server supports LastResourceOptimization, the resource adapter can
participate in a global transaction, provided it is the only
LocalTransaction resource that has been enlisted.
Re-Authentication Support
The cicseci resource adapter supports re-authentication. This is the
ability to change the security credentials when a connection is
70 CICS Transaction Gateway: z/OS Administration

equested from the server and an already existing one is allocated
without having to disconnect and reconnect to the EIS. This improves
performance.
Deploying the cicseciRRS resource adapter
Instructions for deploying the J2EE ECI resource adapter in WebSphere
Application Server for z/OS are given below. A full configuration PDF is
available from www.ibm.com/software/ts/cics/library/manuals/ in the
Configuration booklets section.
1. Install the CICS Transaction Gateway for z/OS.
2. Create a work directory in your WebSphere installation directory, for
example /WebSphere390/CB390/jbo.
3. Move the file cicseciRRS.rar file from /deployable to the
directory that you created in step 2.
4. Extract the archive inside the working directory using the command:
jar -xvf cicseciRRS.rar
5. Grant permissions on the files extracted:
chmod ugo+x *
Deployment parameters for the ECI resource adapters
6. Create a new conversation in the WebSphere Application Server z/OS
Administration tool.
7. Modify your SYSPLEX definition by selecting the Connection
Management check box.
8. Modify the J2EE Servers environment variables to add the following to
the CLASSPATH:
/ /cicseciRRS.jar
/ /cicsframe.jar
/ /ctgclient.jar
/ /ctgserver.jar
9. Modify the LIBPATH statement to point to the working directory created
in step 2.
10. Add a J2EE resource and give it a suitable name. Select the J2EE resource
type CICS_ECIConnectionFactory.
11. Add a J2EE Resource instance to the newly created resource. The name of
the resource instance (CICS_ECIConnectionFactory instance name) will be
the name that your bean looks up to get a connection.
12. Fill in the fields appropriate to your system.
13. Ensure you have saved all updates, and then activate your conversation.
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 the ECI resource adapter. The CICS resource adapters support
four levels of trace:
Chapter 5. Configuring the CICS Transaction Gateway 71

Tracing
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.
Control of where trace is output is handled by the ConnectionManager being
used by your environment. 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 may 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:
/u/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.
72 CICS Transaction Gateway: z/OS Administration

Other configuration tasks:
To complete the configuration of CICS Transaction Gateway, do the following:
v Configure CICS for the EXCI requests from the CICS Transaction Gateway.
Information about this task is given in the CICS External Interfaces Guide.
v Create conversion templates to be used to translate the communication area
used by the CICS programs requested by Web browsers. Information for
this task is given in CICS Family: Communicating from CICS on System/390.
Increasing the CPUTIME timeout when the volume of traffic is high
The BPXPRMxx parmlib member contains the parameters that control
processing and the file system. The system uses these values during
initialization.
Tracing
It may be necessary to change the MAXCPUTIME value in the BPXPRMxx
member in SYS1.PARMLIB if there is a high volume of traffic. This value
determines the maximum amount of CPU time in seconds that a process may
use. BPXPRMxx is used to set an initial value at IPL, which you can modify
using the SETOMVS command.
From OS/390 Version 2.8 onwards, you can set this value on a user ID basis
using the CPUTIMEMAX value in the RACF user ID profile’s OMVS segment.
For more information, see the OS/390 UNIX System Services Planning. book.
Chapter 5. Configuring the CICS Transaction Gateway 73

74 CICS Transaction Gateway: z/OS Administration

Chapter 6. Network Security
This chapter describes how to set up CICS Transaction Gateway to use the
network security protocols SSL and HTTPS. For information on using RACF
to authenticate ECI userids and passwords, see “Configuring CICS Transaction
Gateway for use with RACF ® ” on page 65. This chapter consists of the
following:
“Determining your use of SSLight or JSSE
for the SSL and HTTPS protocols” on
page 76
“Maintaining your digital certificates for
SSLight” on page 76
“Using externally signed certificates
under SSLight” on page 77
“Using self-signed certificates under
SSLight” on page 82
Read this for information on how CICS
Transaction Gateway determines whether
you are using SSLight or JSSE.
Read this for information on using the
IBM Key Management utility iKeyMan
for managing your digital certificates for
SSLight.
Read this for information on how to
configure an SSL server and SSL clients to
use externally signed digital certificates
under SSLight.
Read this for information on how to
configure an SSL server and SSL clients to
use self-signed digital certificates under
SSLight.
“Migration from SSLight” on page 86 Read this for information on migrating
from SSLight to JSSE.
“Installation” on page 86 Read this for information on installing
JSSE.
“Maintaining your digital certificates for
JSSE” on page 87
“Using externally signed certificates
under JSSE” on page 87
“Using self-signed certificates under JSSE”
on page 91
Read this for information on using the
IBM Key Management utility iKeyMan
for managing your digital certificates for
JSSE.
Read this for information on how to
configure an SSL server and SSL clients to
use externally signed digital certificates
under JSSE.
Read this for information on how to
configure an SSL server and SSL clients to
use self-signed digital certificates under
JSSE.
© Copyright IBM Corp. 1996, 2002 75

|
|
Security
“Maintaining your digital certificates for
System SSL” on page 95
“Using externally signed certificates
under System SSL” on page 96
“Using self-signed certificates under
System SSL” on page 101
“Mapping client certificates to RACF
userids” on page 105
“Configuring CICS Transaction Gateway
for SSL and HTTPS” on page 107
“Other security considerations” on
page 108
Read this for information on using
gskkyman, the System SSL tool provided
by z/OS for managing your digital
certificates.
Read this for information on how to
configure an SSL server and SSL clients to
use externally signed digital certificates
under System SSL.
Read this for information on how to
configure an SSL server and SSL clients to
use self-signed digital certificates under
System SSL.
Read this for information on mapping
client certificates to RACF userids.
Read this for information on how to
configure CICS Transaction Gateway to
use the secure protocols.
Read this for information on other
security considerations.
Determining your use of SSLight or JSSE for the SSL and HTTPS protocols
CICS Transaction Gateway determines whether you wish to use SSLight or
JSSE as follows:
v If you pass a KeyRing class to the Gateway daemon, CICS Transaction
Gateway assumes that you are using SSLight.
v If you pass a KeyStore file to the Gateway daemon, CICS Transaction
Gateway assumes that you are using JSSE.
SSLight
Conflict with JSSE
SSLight might not function correctly if JSSE is installed on your system. If
JSSE is installed, rename file gskikm.jar, intheJRE/EXT directory.
Maintaining your digital certificates for SSLight
iKeyMan
Use the ctgikey command to invoke iKeyMan for certificate management.
With iKeyMan, you can:
v Request and receive a digital certificate from a Certification Authority (CA),
see “Using externally signed certificates under SSLight” on page 77.
76 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
Maintaining your digital certificates for SSLight
v Generate self-signed certificates, see “Using self-signed certificates under
SSLight” on page 82.
v Add certificates to your KeyRing files.
v Change your KeyRing 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 KeyRing.
Distributing iKeyMan to client workstations
Although you perform most of the KeyRing management on the CICS
Transaction Gateway machine, you might need to distribute the iKeyMan tool
to clients connecting to your SSL server. The client machines must have the
minimum level of CICS Transaction Gateway Java support; see “Software
requirements” on page 20. They might also require a script or command file to
invoke the iKeyMan Java startup class.
These examples assume that the client workstation has the following files in
the ikeyman directory:
v cfwk.zip
v cfwk.sec
v gsk5cls.jar
v ikminit.properties
All of these files are in the /classes subdirectory.
Using iKeyman in DBCS environments
If you have trouble running iKeyman in your locale, you can use this
command to run it in English:
java -classpath "/classes/cfwk.zip:
/classes/gsk5cls.jar:"
-Dkeyman.javaOnly=true
-Dkeyman.lang=en_US com.ibm.gsk.ikeyman.Ikeyman
Using externally signed certificates under SSLight
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. The following sections
describe how to configure an SSL server and SSL clients using iKeyMan.
Configuring your SSL server and clients involves:
1. Creating a KeyRing class
2. Creating a certificate request
3. Obtaining a digital certificate
Chapter 6. Network Security 77

Using externally signed certificates under SSLight
4. Receiving the digital certificate into the KeyRing
Configuring your SSL server
This section describes how to obtain a Test Server Certificate from the
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a
period of 14 days. As this certificate is for demonstration only it is not signed
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All
SSL clients need the VeriSign Test signer certificate root key to be installed in
their client KeyRings, or, in the case of HTTPS connections, the repository in
the browser. Obtaining a full VeriSign Server Certificate follows the same
procedures as described here for the test version.
1. Create a server KeyRing
The first step is to create a server KeyRing class. This will contain 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 using the command ctgikey.
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyServerKeyRing.class
e. In Location, type a suitable location to store your server KeyRing
The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing 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 MyServerKeyRing.class contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
78 CICS Transaction Gateway: z/OS Administration

Using externally signed certificates under SSLight
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 80.
2. Create a Certificate Request
Before you can obtain a Server Certificate from VeriSign, you must make a
Certificate Request and store it locally:
a. From iKeyMan, select Create —> New Certificate Request.
b. Complete the certificate request. Some fields are optional, but you must
fill in at least the following (examples are shown):
Key Label verisignServerCert
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
c. Specify the name of a file in which to store the certificate request, or
accept the default.
d. Select OK.
iKeyMan generates a public/private key pair.
3. Obtain a Server Certificate
The next step is to connect to the VeriSign Web site and request a Test
Server Certificate:
a. Point your Web browser at: www.verisign.com and navigate to their
request Test Server Certificate application pages.
b. Open the certificate request file you created earlier, using an ASCII text
editor.
Figure 13 on page 80 shows an example of a certificate request.
c. During the Test Server Certificate request process you will be asked to
submit your CSR — Copy and paste the contents of the file into the
text box in the Web page.
d. Verify the contents of your certificate request and provide the personal
details when requested.
If you are requesting a full VeriSign Server ID, rather than a test
version, these details are used to authenticate your application.
e. VeriSign processes your enrollment and sends an e-mail to the address
specified in your personal details.
This e-mail contains your Test Server Certificate, and instructions on
how to:
Chapter 6. Network Security 79

Using externally signed certificates under SSLight
v install a Test Server ID
v install a special Test CA Root
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIB1jCCAT8CAQAwgZUxIDAeBgNVBAMTF2NocmlzdHAuaHVyc2xleS5pYm0u
Y29tMRswGQYDVQQLExJDbGllbnRzICsgR2F0ZXdheXMxDzANBgNVBAoTBklC
TSBVSzETMBEGA1UEBxMKV0luY2hlc3RlcjEOMAwGA1UECBMFSGFudHMxETAP
BgNVBBETCFNPMjEgMkpOMQswCQYDVQQGEwJHQjCBnzANBgkqhkiG9w0BAQEF
AAOBjQAwgYkCgYEAkAth9Ar6k6ijNZ3JxdPGH6yiikwYTuA0RZDLZBSpaSEx
4qNKN/CrdF1LgfQYbZcN5NGCeC4sC478NhT+ltf5dnR3pNWBzEzmWn5mN0lH
tqJ3oibOUmDui+tQc2J9z6iRBKjkcQwjPlJp0sp5KKsev1ahAETL7LqmqMIq
pJlzKi0CAwEAAaAAMA0GCSqGSIb3DQEBBAUAA4GBAHaMHpizPs8Q3bi3I6dh
4yw0UNhojTlS1+ffiph3hK98lMHJuMztr0UMBLl/SZGNw85OJRiWuDjGYUQW
inJ0uNH34IUsnygBmt78+WlXT5nJuayg+UrAc5Ao2H8QZpRE5Sfaoc8lQcvY
plTggCdMxpYN7I33LrZDl3Po0TT8gjxQ
-----END NEW CERTIFICATE REQUEST-----
Figure 13. Example certificate request
4. Receive the Server Certificate into the server KeyRing
When you have obtained the Server Certificate, you use iKeyMan to
receive it into the server KeyRing.
a. Copy and paste the Server Certificate data into a blank text file, using
an ASCII text editor; save the file as verisignServerID.arm.
b. From iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
c. Select Receive...
d. In the Data type pull-down, select Base64-encoded ASCII
e. Type the name and location of the text file containing your Server
Certificate data
f. Select OK.
g. Select Key Database File then Exit.
Your server KeyRing MyServerKeyRing.class is now ready for use with
CICS Transaction Gateway. It contains the default signer certificates, as
well as your VeriSign Server Certificate and its corresponding private key.
Configuring your SSL clients
In normal operation, CICS Transaction Gateway uses only server
authentication when performing an SSL handshake; the client need only
accept the presented Server Certificate. For server authentication to work, the
client KeyRing class, or in the case of HTTPS, the browser certificate
repository, must contain the signer certificate of the Server Certificate. In our
example, the signer certificate is the VeriSign Test signer certificate.
In addition to server authentication, the CICS Transaction Gateway also
supports client authentication. With this option enabled, any connection
80 CICS Transaction Gateway: z/OS Administration

Using externally signed certificates under SSLight
attempted to either the ssl: or https: handler requires the client to present its
own Client Certificate, which is also known as a Digital ID.
The following sections describes how to obtain a VeriSign Digital ID.
1. Create a client KeyRing
A client KeyRing class 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 KeyRing class is similar to that for a
server:
a. Start iKeyMan using the command ctgikey
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyClientKeyRing.class
e. In Location, type a suitable location to store your client KeyRing
The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
h. Select OK.
Like the server KeyRing class, the client KeyRing class contains a default
selection of popular signer certificates.
2. Obtain a Client Certificate
Unlike Server Certificates, you do not need to create a certificate request to
obtain a Client Certificate. VeriSign provides a method of obtaining a Class
1 Digital ID using either Netscape or Internet Explorer browsers.
When you have obtained the Client Certificate and installed it in the
browser repository, you can export the certificate data, together with its
associated private key, into a secure file known as a #PKCS12 file. This file
is password protected and can be imported into a client KeyRing class
using the iKeyMan tool.
a. Point your Web browser at: www.verisign.com
b. Follow the links on their Web site to buy a Class 1 Digital ID from
their Secure E-Mail certificates product area.
c. Complete the enrollment form as requested. The details will be used by
VeriSign to authenticate the client application.
d. VeriSign will send information for downloading and installing the
Class 1 Digital ID to the e-mail address you supplied in your
application.
During the installation process, your browser allows you to store the
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool
Chapter 6. Network Security 81

Using externally signed certificates under SSLight
supports #PKCS12 files and allows you to import certificates, along with
their private key, into a client KeyRing class.
3. Import the Client Certificate into the client KeyRing
To import the #PKCS12 file containing the Client Certificate:
a. In iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
b. Select Import...
c. Set Key file type to PKCS12 file.
d. Type the name and location of the #PKCS12
e. Select OK.
f. Select Key Database File —> Close
g. Select Key Database File —> Exit
Your client KeyRing MyClientKeyRing.class is now ready for use with CICS
Transaction Gateway. It contains the default signer certificate, as well as your
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding
private-key.
Using self-signed certificates under SSLight
CICS Transaction Gateway provides a way for you to “self-sign” your
certificates. You establish yourself as your own Certification 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 KeyRing classes
2. creating digital certificates
3. exporting and importing the certificates
Configuring your SSL server
1. Create a server KeyRing
The first step is to create a server KeyRing class. This will contain 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 using the command ctgikey.
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyServerKeyRing.class
e. In Location, type a suitable location to store your server KeyRing
82 CICS Transaction Gateway: z/OS Administration

The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing 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 MyServerKeyRing.class contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
Using self-signed certificates under SSLight
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 80.
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 KeyRing class:
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
Chapter 6. Network Security 83

Using self-signed certificates under SSLight
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, 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 handshake with this SSL server.
Configuring your SSL clients
1. Create a client KeyRing
A client KeyRing class 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 KeyRing class is similar to that for a
server:
a. Start iKeyMan using the command ctgikey
b. Select Key Database File —> New.
c. From Key Database Type, select SSLight key database class.
d. In File name type a name for your keyring, such as
MyClientKeyRing.class
e. In Location, type a suitable location to store your client KeyRing
The default location is the /bin subdirectory.
f. Select OK.
g. Type a password for the KeyRing file.
h. Select OK.
Like the server KeyRing class, the client KeyRing class contains a default
selection of popular signer certificates.
2. Import the server’s signer certificate
84 CICS Transaction Gateway: z/OS Administration

Using self-signed certificates under SSLight
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.
If the SSL handler used by the CICS Transaction Gateway is configured to
support only server authentication, skip step 3; the client KeyRing need
contain only the signer certificate of the Server, which you have now
imported. You can use the generated MyClientKeyRing.class file with
CICS Transaction Gateway’s SSL protocol, which is configured to support
server authentication.
3. Create a Client Certificate
Client authentication requires the client KeyRing class 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. 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
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...
Chapter 6. Network Security 85

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under SSLight
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 handshake with this SSL client.
Migrating old self-signed certificates
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 KeyRing class files, created with Version 3.0,
using the iKeyMan tool.
Restricting access to the server KeyRing
The contents of the server KeyRing are encrypted and protected by a
password. However IBM recommends that you:
v ensure that the KeyRing class files have appropriate security access
permissions
v restrict access, where applicable, to the CICS Transaction Gateway machine
Do not share certificates among servers. Do not allow servers to share a
private key, particularly if they are running on different machines. Never send
a private key to someone else.
Java Secure Socket Extension (JSSE)
Migration from SSLight
To avoid possible conflicts between the different versions of iKeyMan used in
SSLight and JSSE, IBM strongly recommends that you perform all migration
actions before you install JSSE.
To migrate from SSLight to JSSE:
v Create new KeyStores and use these instead of existing KeyRing classes
v Change existing security exits that implement the SSLightServerSecurity
interface to implement the JSSEServerSecurity interface
Installation
See “Software requirements” on page 20 for details of environments in which
JSSE is supported.
You might need to update the lib/security/java.security file. In this file,
locate the lines which begin security.provider and add a line like the
following if it does not already exist:
86 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
security.provider.=com.ibm.crypto.provider.IBMJCE
where is the next number in sequence following any existing entries.
Maintaining your digital certificates for JSSE
iKeyMan
Use the following command to start the iKeyMan program:
java com.ibm.ikeyman.Ikeyman
With iKeyMan, you can:
v Request and receive a digital certificate from a Certification Authority (CA),
see “Using externally signed certificates under SSLight” on page 77.
v Generate self-signed certificates, see “Using self-signed certificates under
SSLight” on page 82.
v Add certificates to your KeyStore files.
v Change your KeyStore 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 KeyStore.
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. The following sections
describe how to configure an SSL server and SSL clients using iKeyMan.
Configuring your SSL server and clients involves:
1. Creating a KeyStore
2. Creating a certificate request
3. Obtaining a digital certificate
4. Receiving the digital certificate into the KeyStore
Installing JSSE
Configuring your SSL server
This section describes how to obtain a Test Server Certificate from the
VeriSign Web site. VeriSign allows the use of a Test Server Certificate for a
period of 14 days. As this certificate is for demonstration only it is not signed
by the trusted VeriSign Certificate Authority, but by a VeriSign test CA. All
SSL clients need the VeriSign Test signer certificate root key to be installed in
their client KeyStores, or, in the case of HTTPS connections, the repository in
the browser. Obtaining a full VeriSign Server Certificate follows the same
procedures as described here for the test version.
1. Create a server KeyStore
Chapter 6. Network Security 87

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
The first step is to create a server KeyStore. This will contain 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 KeyStore, such as
MyServerKeyStore.jks
e. In Location, type a suitable location to store your server KeyStore
f. Select OK
g. Type a password for the KeyStore 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 MyServerKeyStore.jks contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 89.
2. Create a Certificate Request
Before you can obtain a Server Certificate from VeriSign, you must make a
Certificate Request and store it locally:
a. From iKeyMan, select Create —> New Certificate Request.
b. Complete the certificate request. Some fields are optional, but you must
fill in at least the following (examples are shown):
Key Label verisignServerCert
Key Size select 1024
88 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
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
c. Specify the name of a file in which to store the certificate request, or
accept the default.
d. Select OK.
iKeyMan generates a public/private key pair.
3. Obtain a Server Certificate
The next step is to connect to the VeriSign Web site (www.verisign.com)
and request a Test Server Certificate. You will be asked to paste in the
contents of the certificate request file you created earlier (Figure 13 on
page 80 shows an example of a certificate request) and agree to their
licensing conditions. VeriSign will then send you a confirmation e-mail.
This e-mail contains your Test Server Certificate, and instructions on how
to:
v install a Test Server ID
v install a special Test CA Root
4. Receive the Server Certificate into the server KeyStore
When you have obtained the Server Certificate, you use iKeyMan to
receive it into the server KeyStore.
a. Copy and paste the Server Certificate data into a blank text file, using
an ASCII text editor; save the file as verisignServerID.arm.
b. From iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
c. Select Receive...
d. In the Data type pull-down, select Base64-encoded ASCII
e. Type the name and location of the text file containing your Server
Certificate data
f. Select OK.
g. Select Key Database File then Exit.
Your server KeyStore MyServerKeyStore.jks is now ready for use with
CICS Transaction Gateway. It contains the default signer certificates, as
well as your VeriSign Server Certificate and its corresponding private key.
Configuring your SSL clients
In normal operation, CICS Transaction Gateway uses only server
authentication when performing an SSL handshake; the client need only
accept the presented Server Certificate. For server authentication to work, the
client KeyStore, or in the case of HTTPS, the browser certificate repository,
Chapter 6. Network Security 89

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
must contain the signer certificate of the Server Certificate. In our example,
the signer certificate is the VeriSign Test signer certificate.
In addition to server authentication, the CICS Transaction Gateway also
supports client authentication. With this option enabled, any connection
attempted to either the ssl: or https: handler requires the client to present its
own Client Certificate, which is also known as a Digital ID.
The following instructions describe how to obtain a VeriSign Digital ID.
1. Create a client KeyStore
A client KeyStore class 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 KeyStore class 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 KeyStore, such as
MyClientKeyStore.jks
e. In Location, type a suitable location to store your client KeyStore
f. Select OK
g. Type a password for the KeyStore file.
h. Select OK
Like the server KeyStore, the client KeyStore contains a default selection of
popular signer certificates.
2. Obtain a Client Certificate
Unlike Server Certificates, you do not need to create a certificate request to
obtain a Client Certificate. VeriSign provides a method of obtaining a Class
1 Digital ID using either Netscape or Internet Explorer browsers.
When you have obtained the Client Certificate and installed it in the
browser repository, you can export the certificate data, together with its
associated private key, into a secure file known as a #PKCS12 file. This file
is password protected and can be imported into a client KeyStore using
the iKeyMan tool.
a. Point your Web browser at: www.verisign.com
b. Follow the links on their Web site to buy a Class 1 Digital ID from
their Secure E-Mail certificates product area.
c. Complete the enrollment form as requested. The details will be used by
VeriSign to authenticate the client application.
90 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using externally signed certificates under JSSE
d. VeriSign will send information for downloading and installing the
Class 1 Digital ID to the e-mail address you supplied in your
application.
During the installation process, your browser allows you to store the
Client Certificate in a password protected #PKCS12 file. The iKeyMan tool
supports #PKCS12 files and allows you to import certificates, along with
their private key, into a client KeyStore.
3. Import the Client Certificate into the client KeyStore
To import the #PKCS12 file containing the Client Certificate:
a. In iKeyMan, select Personal Certificates from the pull-down menu
below the Key database content label.
b. Select Import...
c. Set Key file type to PKCS12 file.
d. Type the name and location of the #PKCS12
e. Select OK.
f. Select Key Database File —> Close
g. Select Key Database File —> Exit
Your client KeyStore MyClientKeyStore.jks is now ready for use with CICS
Transaction Gateway. It contains the default signer certificate, as well as your
VeriSign Client Certificate (Class 1 Digital ID) and its corresponding
private-key.
Using self-signed certificates under JSSE
CICS Transaction Gateway provides a way for you to “self-sign” your
certificates. You establish yourself as your own Certification 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 KeyStores
2. creating digital certificates
3. exporting and importing the certificates
Configuring your SSL server
1. Create a server KeyStore
The first step is to create a server KeyStore. This will contain 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
Chapter 6. Network Security 91

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
b. Select Key Database File —> New
c. From Key Database Type, select JKS
d. In File name type a name for your KeyStore, such as
MyServerKeyStore.jks
e. In Location, type a suitable location to store your server KeyStore
f. Select OK
g. Type a password for the KeyStore 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 MyServerKeyStore.jks contains, by default, a selection
of popular signer certificates as follows:
VeriSign Class 3 Public Primary Certification Authority
VeriSign Class 2 Public Primary Certification Authority
VeriSign Class 1 Public Primary Certification Authority
RSA Secure Server Certification 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
The VeriSign Class 1 through 3 Public Primary Certification Authority
signer certificates enable the server to verify clients with VeriSign Client
Certificates. This is explained in more detail in “Configuring your SSL
clients” on page 89.
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 KeyStore:
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
92 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
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, 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 handshake with this SSL server.
Configuring your SSL clients
1. Create a client KeyStore
A client KeyStore class 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 KeyStore class 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 KeyStore, such as
MyClientKeyStore.jks
e. In Location, type a suitable location to store your client KeyStore
f. Select OK
g. Type a password for the KeyStore file.
h. Select OK
Chapter 6. Network Security 93

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Using self-signed certificates under JSSE
Like the server KeyStore, the client KeyStore 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.
If the SSL handler used by the CICS Transaction Gateway is configured to
support only server authentication, skip step 3; the client KeyStore need
contain only the signer certificate of the Server, which you have now
imported. You can use the generated MyClientKeyStore.jks file with CICS
Transaction Gateway’s SSL protocol, which is configured to support server
authentication.
3. Create a Client Certificate
Client authentication requires the client KeyStore 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. 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
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.
94 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
System SSL
Using self-signed certificates under JSSE
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 handshake with this SSL client.
Migrating old self-signed certificates
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 KeyStore files, created with Version 3.0, using the
iKeyMan tool.
Restricting access to the server KeyStore
The contents of the server KeyStore are encrypted and protected by a
password. However IBM recommends that you:
v ensure that the KeyStore files have appropriate security access permissions
v restrict access, where applicable, to the CICS Transaction Gateway machine
Do not share certificates among servers. Do not allow servers to share a
private key, particularly if they are running on different machines. Never send
a private key to someone else.
Maintaining your digital certificates for System SSL
System SSL is part of Cryptographic Services, an optional feature of the z/OS
operating system. It includes the gskkyman utility for maintaing your digital
certificates. The gskkyman utility runs in either an rlogin shell environment or
in the OMVS shell command line environment.
With gskkyman you can:
v Create a key database
v Create a certificate request (and public/private key pair)
v Create a self-signed certificate
v Export a certificate request to a file
v Receive a certificate after a certificate request has been fulfilled
v Export a certificate to a file
v Import a certificate from a file
Chapter 6. Network Security 95

Maintaining your digital certificates for System SSL
v Mark a certificate as a trusted CA certificate
v Mark a certificate (and private key) as the default certificate for the key
database
v List certificate information
v Remove a certificate (and private key) from a key database
v Remove a key database.
For further information on gskkyman, type the following command to display
help information:
gskkyman -h
or see Cryptographic Services System Secure Sockets Layer Programming Guide and
Reference. SC24–5877.
Using externally signed certificates under System SSL
The following sections describe how to configure CICS Transaction Gateway
as a System SSL server to use externally signed certificates. This involves:
1. Creating a key database
2. Creating a certificate request
3. Receiving the certificate after the request has been fulfilled
4. Storing the certificate as a Trusted CA Certificate
Configuring your System SSL server
1. Create a key database
a. Type gskkyman
This displays the IBM Key Management Utility menu:
IBM Key Management Utility
Choose one of the following options to proceed.
1 - Create new key database
2 - Open key database
3 - Change database password
0 - Exit program
Enter your option number: 1
b. Type 1 (Create new key database), then respond to the prompts as
follows:
96 CICS Transaction Gateway: z/OS Administration
Enter key database name or press ENTER for "key.kdb":
mykey.kdb
Enter password for the key database.......> mypasswd
Enter password again for verification.....> mypasswd
Should the password expire? (1 = yes, 0 = no) [1]:
Enter password expiration time (number of days) or press ENTER
for 60 days: 35

Using externally signed certificates under System SSL
Press Enter to save these values.
c. The following message and prompt appears:
The database has been
successfully created, do you want to continue to work
with the database now? (1 = yes, 0 = no) [1]:
Type 1 or press Enter
This displays the Key Database menu, which allows you to continue
configuring the SSL server:
Key database menu
Current key database is /u/home/mykey.kdb
1 - List/Manage keys and certificates
2 - List/Manage request keys
3 - Create new key pair and certificate request
4 - Receive a certificate issued for your request
5 - Create a self-signed certificate
6 - Store a CA certificate
7 - Show the default key
8 - Import keys
9 - Export keys
10 - List all trusted CAs
11 - Store encrypted database password
0 - Exit program
Enter option number (or press ENTER to return to the parent menu):
The gskkyman utility creates the key database as a file, mykey.kdb in our
example, in the hierarchical file system (HFS) of z/OS Unix System Services.
You must include this file in the system LIBPATH environment variable.
2. Create a certificate request (and public/private key pair)
a. From the Key Database menu, type 3 (Create new key pair and
certificate request)
b. Respond to the prompts as follows:
Chapter 6. Network Security 97

Using externally signed certificates under System SSL
Enter certificate request file name or press ENTER for "certreq.arm": servercertreq.arm
Enter a label for this key................> My CA
Select desired key size from the following options (512):
1: 512
2: 1024
Enter the number corresponding to the key size you want: 1
Enter certificate subject name fields in the following.
Common Name (required)................> myserver
Organization (required)...............> my org
Organization Unit (optional)..........>
City/Locality (optional)..............>
State/Province (optional).............>
Country Name (required 2 characters)..> UK
Please wait while key pair is created...
Your request has completed successfully, exit gskkyman?
(1 = yes, 0 = no) [0]: 0
Some fields are optional, but you must fill in at least the following
(examples are shown):
Request file name The default is servercertreq.arm
Key label For example: My CA
Key size select 512
Common name The name of the server machine
Organization The name of your organization
Country A two character ID
When you complete the certificate request, gskkyman creates a file,
servercertreq.arm in our example, in the current working directory.
The file is in Base64-encoded format. This is the format usually
required by Certification Authorities (CAs). You can display the
contents of the file using the cat servercertreq.arm command; Figure 14
on page 99 shows an example of a certificate request.
c. Send the request to a CA
Ether transfer the file directly, as a text file, or copy it into an e-mail
message.
98 CICS Transaction Gateway: z/OS Administration

Using externally signed certificates under System SSL
-----BEGIN NEW CERTIFICATE REQUEST-----
MIH7MIGmAgEAMEExCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNJQk0xETAPBgNVBAsT
CEVuZGljb3R0MREwDwYDVQQDEwhKb2huIERvZTBcMA0GCSqGSIb3DQEBAQUAA0sA
MEgCQQCrIZdRnXhH1EMAwTuKMKYznCFp4CFk0YG66BhvMGgfTwql9aSRWkVcer8I
I7Qk9aYzQ2LIpRhloJ9ugojy1I9VAgMBAAGgADANBgkqhkiG9w0BAQQFAANBAFc1
xOfunjyt54dUqGDdPgbnMr5A3trUhzHHkX8xlfH9Albrpsv2a3FjvnmYWFPuFXAf
3ABCD5nnsbk3AP++ic5UTM=
-----END NEW CERTIFICATE REQUEST-----
Figure 14. Example certificate request
3. Receive the certificate
When the CA returns a certificate to you, use gskkyman to receive it into
the key database. Usually the CA sends an e-mail message containing a
Base64-encoded certificate.
To receive a certificate:
a. Store the certificate in an HFS file on your z/OS operating system
This file should be in the current working directory when you start
gskkyman. This example assumes that you stored the certificate as
servercert.arm.
b. Type gskkyman
c. Type 2 (Open key database)
d. At the prompt, type the name of your key database
In our example, the name is mykey.kdb.
e. At the prompt, type your password
f. In the Key Database menu, type 4 (Receive a certificate issued for your
request)
g. Respond to the prompts as follows:
Enter certificate file name or press ENTER for "cert.arm": servercert.arm
Do you want to set the key as the default in your key database?
(1 = yes, 0 = no) [1]:
Please wait while certificate is received......
Your request has completed successfully, exit gskkyman?
(1 = yes, 0 = no) [0]: 0
4. Store the certificate
Some well-known CA certificates are stored in the key database when you
create it. You can display the list of stored CAs by typing 10 (List all
trusted CAs) in the Key Database menu. The default list of stored CAs is:
Chapter 6. Network Security 99

Using externally signed certificates under System SSL
Trust CA certificate list
Key database name is /home/mykey.kdb
Please choose one of the following keys to work with.
1 - Integrion Certification Authority Root
2 - IBM World Registry Certification Authority
3 - Thawte Personal Premium CA
4 - Thawte Personal Freemail CA
5 - Thawte Personal Basic CA
6 - Thawte Premium Server CA
7 - Thawte Server CA
8 - Verisign Test CA Root Certificate
9 - RSA Secure Server Certification Authority
10 - Verisign Class 1 Public Primary Certification Authority
11 - Verisign Class 2 Public Primary Certification Authority
12 - Verisign Class 3 Public Primary Certification Authority
Enter a key number or press ENTER to return to parent menu:
To use a CA that is not one of the defaults you must store the CA’s
certificate in your key database file.
To use client authentication on your SSL connection you must store the
CA’s certificate in the key database of the server program. You must also
store the CA’s certificate in the key database of the client program
regardless of whether the SSL connection uses client authentication.
To store the certificate in your key database as a CA certificate:
a. Store the certificate in an HFS file on your z/OS operating system.
This file should be in the current working directory when you start
gskkyman.
b. Type gskkyman
c. Type 2 (Open key database)
d. At the prompt, type the name of your key database
In our example, the name is mykey.kdb.
e. At the prompt, type your password
f. In the Key Database menu, type 6 (Store a CA certificate)
g. Respond to the prompts as follows:
Enter certificate file name or press ENTER for "cert.arm": servercert.arm
Enter a label for this key................> My CA
Please wait while certificate is stored...
Your request has completed successfully, exit gskkyman?
(1 = yes, 0 = no) [0]: 0
When stored, the certificate is treated as ″trusted″ so that it can be used to
verify incoming certificates.
100 CICS Transaction Gateway: z/OS Administration

Using externally signed certificates under System SSL
For a program acting as an SSL server, this certificate is used to verify a
client’s certificate.
For a program acting as an SSL client, this certificate is used to verify the
server’s certificate, which is sent to the client during the SSL handshake
processing.
Using self-signed certificates under System SSL
The following sections describe how to configure CICS Transaction Gateway
as a System SSL server to use self-signed certificates. This involves:
1. Creating a key database
2. Creating a self-signed certificate
3. Exporting the certificate to SSL clients
Configuring your System SSL server
1. Create a key database
a. Type gskkyman
This displays the IBM Key Management Utility menu:
IBM Key Management Utility
Choose one of the following options to proceed.
1 - Create new key database
2 - Open key database
3 - Change database password
0 - Exit program
Enter your option number: 1
b. Type 1 (Create new key database), then respond to the prompts as
follows:
Enter key database name or press ENTER for "key.kdb":
mykey.kdb
Enter password for the key database.......> mypasswd
Enter password again for verification.....> mypasswd
Should the password expire? (1 = yes, 0 = no) [1]:
Enter password expiration time (number of days) or press ENTER
for 60 days: 35
Press Enter to save these values.
c. The following message and prompt appears:
The database has been
successfully created, do you want to continue to work
with the database now? (1 = yes, 0 = no) [1]:
Type 1 or press Enter
Chapter 6. Network Security 101

Using self-signed certificates under System SSL
This displays the Key Database menu, which allows you to continue
configuring the SSL server:
Key database menu
Current key database is /u/home/mykey.kdb
1 - List/Manage keys and certificates
2 - List/Manage request keys
3 - Create new key pair and certificate request
4 - Receive a certificate issued for your request
5 - Create a self-signed certificate
6 - Store a CA certificate
7 - Show the default key
8 - Import keys
9 - Export keys
10 - List all trusted CAs
11 - Store encrypted database password
0 - Exit program
Enter option number (or press ENTER to return to the parent menu):
The gskkyman utility creates the key database as a file, mykey.kdb in our
example, in the hierarchical file system (HFS) of z/OS Unix System Services.
You must include this file in the system LIBPATH environment variable.
2. Create a self-signed certificate
a. From the Key Database menu, type 5 (Create a self-signed certificate)
b. Respond to the prompts as follows:
102 CICS Transaction Gateway: z/OS Administration

Enter version number of the certificate to be created (1, 2, or 3) [3]: 3
Enter a label for this key................> My Self-signed CA
Select desired key size from the following options (512):
1: 512
2: 1024
Enter the number corresponding to the key size you want: 1
Enter certificate subject name fields in the following.
Common Name (required)................> myserver
Organization (required)...............> my org
Organization Unit (optional)..........>
City/Locality (optional)..............>
State/Province (optional).............>
Country Name (required 2 characters)..> UK
Enter number of valid days for the certificate [365]: 244
Do you want to set the key as the default in your key database? (1 = yes, 0 =
no) [1]:
Do you want to save the certificate to a file? (1 = yes, 0 = no) [1]: 1
Should the certificate binary data or Base64 encoded ASCII data be saved? (1 =
ASCII, 2 = binary) [1]: 1
Enter certificate file name or press ENTER for "cert.arm": servercert.arm
Please wait while self-signed certificate is created...
Your request has completed successfully, exit gskkyman?
(1 = yes, 0 = no) [0]: 0
Using self-signed certificates under System SSL
Some fields are optional, but you must fill in at least the following
(examples are shown):
Version number The X.509 standard version number.
Choose 3.
Key label For example: My Self-signed CA
Key size select 512
Common name The name of the server machine
Organization The name of your organization
Country A two character ID
Validity period The default is 365 days
Set key as default? Setting the key as the default certificate
allows the SSL Toolkit to use the
certificate without having to specify the
distinguished name in calls to System
SSL APIs.
Save certificate to file? Save the certificate in a separate file, as
well as in the key database. You need
Chapter 6. Network Security 103

Using self-signed certificates under System SSL
-----BEGIN NEW CERTIFICATE REQUEST-----
to do this to export the certificate to
your SSL clients; see step 3.
Binary or ASCII? Choose Base64-encoded ASCII. This is
the default.
Certificate file name The default is cert.arm for ASCII and
cert.crt for binary.
If you chose to save the certificate to a file, gskkyman creates the file,
servercert.arm in our example, in the current working directory. You can
display the contents of the file using the cat servercert.arm command;
Figure 15 shows an example of a certificate file in Base64-encoded ASCII
format.
MIH7MIGmAgEAMEExCzAJBgNVBAYTAlVTMQwwCgYDVQQKEwNJQk0xETAPBgNVBAsT
CEVuZGljb3R0MREwDwYDVQQDEwhKb2huIERvZTBcMA0GCSqGSIb3DQEBAQUAA0sA
MEgCQQCrIZdRnXhH1EMAwTuKMKYznCFp4CFk0YG66BhvMGgfTwql9aSRWkVcer8I
I7Qk9aYzQ2LIpRhloJ9ugojy1I9VAgMBAAGgADANBgkqhkiG9w0BAQQFAANBAFc1
xOfunjyt54dUqGDdPgbnMr5A3trUhzHHkX8xlfH9Albrpsv2a3FjvnmYWFPuFXAf
3ABCD5nnsbk3AP++ic5UTM=
-----END NEW CERTIFICATE REQUEST-----
Figure 15. Example certificate file in Base64-encoded ASCII format
3. Export certificates to client programs
All SSL client programs connecting to your SSL server must be able to
treat the self-signed certificate as a trusted CA certificate. For this you
must export the self-signed certificate to all SSL client programs.
a. From the Key Database menu, type 1 (List/Manage keys and
certificates)
This displays the Key and certificate list menu:
Key and certificate list
Key database name is /u/home/mykey.kdb
Please choose one of the following keys to work with.
1 - My Self-signed CA
2 - Integrion Certification Authority Root
3 - IBM World Registry Certification Authority
4 - Thawte Personal Premium CA
5 - Thawte Personal Freemail CA
6 - Thawte Personal Basic CA
7 - Thawte Premium Server CA
8 - Thawte Server CA
9 - Verisign Test CA Root Certificate
Enter a key number or press ENTER for more labels:
104 CICS Transaction Gateway: z/OS Administration

. Type the key number of the certificate you created, My Self-signed CA
in our example.
This displays the Key menu:
Key Menu
Currently selected key: My Self-signed CA
Choose one of the following options to proceed.
1 - Show key information
2 - Set the selected key as default
3 - View certificate of the key
4 - Remove trust root status
5 - Copy the certificate of this key to a file
6 - Copy the certificate request of this key to a file
7 - Delete the key
8 - Export the key to another database
9 - Export the key to a file
0 - Exit program
Using self-signed certificates under System SSL
Enter option number (or press ENTER to return to the parent menu):
c. Type 5 (Copy the certificate of this key to a file.)
d. Respond to the prompts as follows:
Should the certificate binary data or Base64 encoded ASCII data be saved? (1 =
ASCII, 2 = binary) [1]:1
Enter certificate file name or press ENTER for "cert.arm": servercert.arm
Please wait while the certificate is written to a file...
Your request has completed successfully, exit gskkyman?
(1 = yes, 0 = no) [0]: 1
e. Transfer the file, servercert.arm in our example, to the system where
the SSL client program will run.
f. Store the certificate in the SSL client’s key database as a trusted CA
certificate.
Mapping client certificates to RACF userids
This involves:
1. Using the RACF command RACDCERT to associate client certificates with
RACF userids
2. Using a Java class supplied by CICS Transaction Gateway to map
certificates to their associated RACF userids
Associate a client certificate with a RACF userid
1. Perform the actions described in “Configuring CICS Transaction Gateway
for use with RACF ® ” on page 65.
2. Copy the certificate that you wish to process into an MVS sequential file.
Chapter 6. Network Security 105

Mapping client certificates to RACF userids
The file should have variable length, blocked records (RECFM=VB) and be
accessible from TSO.
3. Run the RACDCERT command in TSO.
This command does not run in the UNIX System Services shell.
The syntax of RACDCERT is:
RACDCERT ADD(’datasetname’) TRUST [ ID(userid) ]
where:
datasetname is the name of the data set containing the client certificate.
userid is the userid to be associated with the certificate.
This parameter is optional. If omitted, the certificate is
associated with the user issuing the RACDCERT
command.
When you issue the RACDCERT command, RACF creates a profile in the
DIGTCERT class. This profile associates the certificate with the userid. You
can then use the profile to translate a certificate to a userid without giving a
password.
For further information on the RACDCERT command, including the format
of data allowed in the downloaded certificate data set, see Z/OS Security
Server (RACF) Command Language Reference.
Map a certificate to its associated RACF userid
Use the Java class com.ibm.ctg.util.RACFUserid to map a certificate to a
RACF userid. The class has the following methods:
v setCertificate(byte[] clientCertificateData);
v getRACFUserid();
IBM recommends that you create a RACFUserid as follows:
RACFUserid myUseridObject = new RACFUserid(myCertificate);
This creates an object and automatically populates it with certificate data,
without needing to call the setCertificate(byte[] clientCertificateData);
method. When the object is created, getRACFUserid() makes a native z/OS
call and tries to map the certificate to a RACF userid. If successful, it returns a
string containing the RACF userid.
The SystemSSLServerCompression.java class in the
/samples/java/com/ibm/ctg/samples/security subdirectory
shows an example of creating the RACFUserid object.
106 CICS Transaction Gateway: z/OS Administration

For more information on the com.ibm.ctg.util.RACFUserid class, refer to CICS
Transaction Gateway: Programming Guide.
Configuring CICS Transaction Gateway for SSL and HTTPS
To use the SSL and HTTPS protocols, enable them using the configuration
tool; see “Configuring CICS Transaction Gateway settings” on page 56. You
can specify that either or both of the protocols is used, and you can use SSL
and System SSL at the same time. When you enable the protocols, by default,
CICS Transaction Gateway listens for SSL requests on port 8050, and for
HTTPS requests on port 443. Howevever, to use SSLight and System SSL at
the same time, you must specify unique port numbers for each.
SSL and HTTPS configuration settings
The following configuration settings are specific to the SSL and HTTPS
protocols:
KeyRing database Specifies the name of the System SSL server
key database.
KeyRing or KeyStore name Specifies the name of the server KeyRing or
KeyStore.
For a KeyRing, you must also add the
classname to the CLASSPATH environment
variable.
KeyRing or KeyStore password
Specifies the password used to read the
encrypted server KeyRing or KeyStore.
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 Enables client authentication. The default is
that only server authentication is enabled.
CICS Transaction Gateway provides two default KeyRing class files,
ClientKeyRing and ServerKeyRing, that you can use to establish SSL and HTTPS
connections under SSLight. Both KeyRings have been encrypted using the
password default. Use them only in testing environments.
Specifying a client KeyRing or KeyStore
Your choice of secure protocol determines whether or not you need a
KeyRing, or KeyStore, for both server and client:
HTTPS
Specify a KeyRing or KeyStore only in the server.
Mapping client certificates to RACF userids
Chapter 6. Network Security 107

Configuring CICS Transaction Gateway for SSL and HTTPS
SSL
The SSL protocol requires you to specify KeyRings, or KeyStores for both the
server and the client.
For more information see SSL JavaGateway, inCICS Transaction Gateway:
Programming Guide.
Using the SSL and HTTPS protocols
You use the SSL and HTTPS protocols in a similar way to the TCP and HTTP
protocols. To make a connection to CICS Transaction Gateway, your client
application flows a request using the appropriate URL. For example, for SSL
use a URL like:
ssl://transGatewayMachine:8050
Similarly, for HTTPS:
https://transGatewayMachine:443
For more information on the design and implementation of client-side
programs, see CICS Transaction Gateway: Programming Guide, and the CICS
Transaction Gateway programming interface HTML pages.
Other security considerations
You can find information about other security considerations as follows:
The AUTH_USERID_PASSWORD
environment variable
See “The environment variables” on
page 48
Setting extended attributes on HFS files See “Configuring CICS Transaction
Gateway for use with RACF ® ” on page 65
Setting surrogate options in DFHXCOPT, the
EXCI options module
See “Customizing EXCI options” on
page 50
CICS security for ECI/EXCI calls See CICS Transaction Gateway:
Programming Guide
108 CICS Transaction Gateway: z/OS Administration

Chapter 7. Performance
This chapter helps you to:
v understand the factors that affect CICS Transaction Gateway performance
v achieve the best performance from your system
“Assessing system performance” Read this for an overview of the things to
consider when assessing the performance
of your system.
“CICS Transaction Gateway
configuration” on page 110
Read this for information on CICS
Transaction Gateway configuration
parameters which affect performance.
“Java considerations” on page 112 Read this for information on Java factors
which affect performance.
“Other system factors” on page 113 Read this for information on other system
factors which affect performance.
“Tracing” on page 114 Read this for information on using tracing
to measure performance.
“Performance monitoring tools” on
page 114
Read this for information on performance
monitoring tools.
Assessing system performance
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 WebServer or Web 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.
© Copyright IBM Corp. 1996, 2002 109

CICS Transaction Gateway configuration
CICS Transaction Gateway configuration
IBM has chosen default values for configuration and tuning to give a
compromise between:
v limiting the system resources used by CICS Transaction Gateway after it
has started
v giving 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
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.
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.
If the number of threads needed by applications exceeds the value
specified for Maximum number of Connection Manager threads,
each new request that requires a Connection Manager thread must
wait until a thread becomes available. If the waiting time exceeds the
value specified in the Connection timeout parameter, CICS
Transaction Gateway refuses the connection.
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
110 CICS Transaction Gateway: z/OS Administration

CICS Transaction Gateway configuration
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
v If the value is too low, CICS Transaction Gateway uses resources to
search for available Worker threads.
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 number of transactions per second passing through CICS
Transaction Gateway
v average transaction response time through CICS Transaction
Gateway in seconds
An MVS address space can open a maximum of 100 EXCI pipes. This
means that you cannot improve performance by specifying a value
greater than 100 for Maximum number of Worker threads. However,
if your CICS transactions remain in process for a long time, all of the
EXCI connections could become busy, leaving no Worker threads
available. For example, if the average transaction response time
through CICS is 0.5 seconds, the maximum achievable transaction rate
through a single CICS Transaction Gateway is about 200 transactions
per second.
You can increase throughput by starting multiple gateways; see
“Starting multiple CICS Transaction Gateways” on page 124.
Communication protocols
Your choice of protocol depends on the nature of your client
applications. However, CICS Transaction Gateway does considerably
more processing to handle the HTTP and HTTPS protocols than it
does to handle the TCP and SSL protocols. In addition, when using
HTTP or HTTPS, CICS Transaction Gateway creates a new TCP/IP
connection with each client request. For better performance, use TCP
or SSL in preference to HTTP or HTTPS where possible.
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 may need to change them for
Chapter 7. Performance 111

CICS Transaction Gateway configuration
Java considerations
particular applications. Refer to “Configuring CICS Transaction
Gateway settings” on page 56 for more information on these and all
other configuration parameters.
Connection logging
The gateway configuration setting, Log 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 client
connections and disconnections” on page 58.
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; see
also “java.lang.OutOfMemory exception” on page 143. 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 is enabled by default in JDK 1.3.1. Performance
immediately after a CICS Transaction Gateway has started might be
relatively slow because of JIT overheads. The JIT threshold is 2000 on
JDK 1.3.1 compared with 500 on JDK 1.1.8; that is, each method has to
run 2000 times before it is ’JITed‘. 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
112 CICS Transaction Gateway: z/OS Administration

Other system factors
Other system factors
EXCI connections
When you define your EXCI connections you can chooose between
generic EXCI pipes and specific EXCI pipes. Specific EXCI pipes give
slightly better performance. See “CICS server connection definition”
on page 37 for more information on selecting your EXCI connections.
Region size
The JVM runs within the CICS Transaction Gateway address space.
This means that, if your application requires CICS Transaction
Gateway to create large numbers of threads, for example Connection
Manager threads, you might need to increase the region size. You
define the region size with the REGION parameter in the EXEC
statement in the CICS Transaction Gateway start JCL. See “Region size
considerations” on page 123 for more information on this parameter.
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 may be small , and the amount of data expected from CICS in
return may 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 CICS Transaction Gateway 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 Do not use the deprecated setCommareaInboundLength method
because it prevents automatic commarea null stripping.
CICS server transactions
The design of your CICS server transactions affects the performance of
your system. The response time through CICS Transaction Gateway
might increase if your transactions:
v need to wait for shared resources, for example data sets or
applications, to become available
Chapter 7. Performance 113

Other system factors
Tracing
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, 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 may 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 may 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.
IBM does not recommend the use of the full CICS Transaction Gateway trace
to monitor performance in a production environment. This is because the
trace itself significantly decreases performance.
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 client application, and also
through CICS and WebSphere.
Performance monitoring tools
Resource Management Facility (RMF )
This is a measurement collection tool. It measures selected areas of
system activity which is collected in the form of System Management
Facilty (SMF) records. You can use it to measure processor and I/O
activity in the CICS Transaction Gateway address space, and also to
114 CICS Transaction Gateway: z/OS Administration

Performance monitoring tools
measure similar activity in, for example, the CICS server and
WebSphere. For more information see
Refer also to the performance and tuning documentation for WebSphere,
TCP/IP, CICS Transaction Server for z/OS, and TXSeries .
Chapter 7. Performance 115

116 CICS Transaction Gateway: z/OS Administration

|
|
|
Chapter 8. Operation
This chapter describes how to start and stop the CICS Transaction Gateway
for z/OS. The startup options that you can specify are described.
Testing your configuration
Sample JCL is provided to check that ctgenvvar and CTG.INI are correctly
configured. See /samples/samples.txt for details.
Starting the CICS Transaction Gateway
You can start the gateway:
v From an z/OS UNIX System Services command line.
v By submitting JCL to start a batch job. If you choose this option you can
register with the automatic restart manager component of MVS; see
“Automatic restart management” on page 119.
You can start the gateway with default values for the options, or with
user-supplied values. The options and their values are described in “Starting
the Gateway with user-specified options”.
Starting from a command line
To start the CICS Transaction Gateway with the default options, type ctgstart
at the command prompt and press Enter.
A Gateway console session starts, and the following messages are displayed
showing the values being used:
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,
CCL6502I: Initial Workers = 1, Maximum Workers = 100, Port = 2006
Starting the Gateway with user-specified options
The user definable options on the start command are:
-port=port_number
The TCP/IP port number assigned to the CICS Transaction Gateway
-initconnect=number
The initial number of ConnectionManager threads.
-maxconnect=number
The maximum number of ConnectionManager threads. If this value is set
to -1, no limits are applied to the number of ConnectionManager threads.
© Copyright IBM Corp. 1996, 2002 117

Operation
-truncationsize=nnn
Specifies the maximum size of any data blocks shown in the trace, where
nnn is any positive integer. You can use this option in addition to either
-trace or -x and this overrides the default size set by these options. For
example, to switch on standard tracing and dump a maximum of 20,000
bytes:
ctgstart -trace -truncationsize=20000
If you specify a value of 0, no data blocks are shown in the trace.
-dumpoffset=offset
Specifies the offset from which displays of any data blocks start. If the
specified offset is greater than the total length of data, the data is dumped
as if the offset were 0.
-initworker=number
The initial number of Worker threads.
-maxworker=number
The maximum number of Worker threads. If this value is set to -1, no
limits are applied to the number of Worker threads.
-trace
This is the standard trace option (see “Tracing” on page 133). It only traces
the first 80 bytes of the COMMAREA by default.
If you used the configuration tool to configure your Gateway, the default
destination for the trace output is the file CTG.TRC in the
/bin subdirectory. Otherwise, trace output is written to
stderr.
-stack
Enables exception stack tracing only. All checked Java exceptions are
traced, including exceptions that are expected during normal operation of
the CICS Transaction Gateway, but no other tracing is done.
-tfile=pathname
If tracing is enabled, writes the trace messages to the file specified in
pathname. This overrides the default destination for trace output (see the
-trace option).
-tfilesize=number
Specifies the maximum size, in kilobytes, of the trace text file.
-noinput
Disables the reading of input from the console. In this case, you can not
stop the Gateway by input to the console session, “Stopping the CICS
Transaction Gateway” on page 127.
-x Enables full debug tracing. This includes everything traced by the -trace
118 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
option, plus additional information including information about the
internal workings of the CICS Transaction Gateway. This option traces the
entire COMMAREA by default.
This option will decrease performance significantly.
-dnsnames
Enables the display of symbolic TCP/IP hostnames in messages.
-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 switch.
To override the startup defaults, type: ctgstart at the command prompt,
followed by the startup options you require, and press Enter.
A Gateway console session starts, and the following messages are displayed
showing the values being used:
CCL6502I: Initial ConnectionManagers = 1, Maximum ConnectionManagers = 100,
CCL6502I: Initial Workers = 1, Maximum Workers = 100, Port = 2006
To get help for the startup options, enter: ctgstart ?
For more information about the start options related to tracing, see “Tracing”
on page 133.
Automatic restart management
See /samples/samples.txt for details of sample JCL provided.
If you start the CICS Transaction Gateway with JCL (see “Starting with JCL”
on page 121), you can register the job with z/OS Automatic Restart Manager
(ARM). This allows MVS to restart the Gateway automatically if it fails, or if
the system on which it was running fails.
MVS automatic restart management is a sysplex-wide integrated automatic
restart mechanism that:
v Restarts an MVS subsystem in place if it abends (or if a monitor program
notifies ARM of a stall condition)
v Restarts all the elements of a workload (for example, CICS TORs, AORs,
FORs, DB2 ® , and so on) on another MVS image after an MVS failure
v Restarts CICS data sharing servers in the event of a server failure
v Restarts a failed MVS image
The main benefits of ARM are that it:
v Eliminates the need for operator-initiated restarts, or restarts by other
automatic packages, thereby:
Operation
Chapter 8. Operation 119

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Operation
– Improving emergency restart times
– Reducing errors
– Reducing complexity
v Provides cross-system restart capability. It ensures that the workload is
restarted on MVS images with spare capacity, by working with the MVS
workload manager.
v Allows all elements within a restart group to be restarted in parallel. Restart
levels (using the ARM WAITPRED protocol) ensure the correct starting
sequence of dependent or related subsystems.
Prerequisites
To use ARM you need ARM and a Sysplex controller. You need to define
policies for automatic restart management; see z/OS MVS Programming: Sysplex
Services Guide, SA22-7617.
Use the ctgarm command to register the Gateway; see “Starting with JCL” on
page 121 for examples of how to use the command. This comand file is
installed into the /bin subdirectory. You must mark ctgarm as
APF-authorized. To issue the following command, you must be the owner of
the ctgarm file, or a superuser. You also need authority to update RACF group
BPX.FILEATTR.APF:
extattr +a /bin/ctgarm
To verify that you have the necessary authority, proceed as follows:
1. Log on to MVS.
2. Run ISPF.
3. Choose option 6 (Command).
4. Issue the following command:
SR CLASS(FACILITY)
Check that this entry appears in the list:
BPX.FILEATTR.APF
The ctgarm command takes one of the following parameters:
v ’R[egister] ARM_ID [ARM_TYPE]’
v ’D[eregister]’
ARM_ID is a unique 16–character ID. ARM_TYPE is an 8–character restart
level; the default is SYSLVL2. Valid characters for both ARM_ID and
ARM_TYPE are:
v Uppercase alphabetic characters
v The numbers 0 through 9
120 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
v $, #, @, and underscore (_).
The first character may not be a number.
The ctgarm command returns the following codes:
0 No errors.
4 Restarting.
8 Miscellaneous error, including already registered or not unique ID.
12 Severe error, for example ARM is not installed.
Operation
For ARM error codes see z/OS MVS Programming: Sysplex Services Reference,
SA22-7618.
For more information about Automatic Restart Management, see z/OSV1R2.0
MVS Setting up a Sysplex, SA22–7625.
Starting with JCL
See /samples/samples.txt for details of sample JCL provided.
Table 7 is a sample of the JCL you can use to start the CICS Transaction
Gateway as a batch job. The job is shown here as a series of stages so that you
can modify it if you do not wish to use ARM. Code the job in the normal
way; do not include the entries in the Stage column.
Table 7. Sample JCL to register the Gateway with ARM and start it as a batch job
Stage Code
1. //DFHJGATE JOB (Accounting info),CLASS=A,USER=user,PASSWORD=passwd,
// MSGCLASS=H
2a. //* Name to identify this JCL run
// SET CTGNAME=’CTG’
2b. //* Unique ID for ARM and used to identify this JCL run
// SET CTGNAME=’CTG_RESTART_ARM1’
3a. //* Fixed file names for log files
// SET CTGLOG=’/logs/ctgo.log’
// SET CTGERR=’/logs/ctge.log’
// SET CTGDIR=’/bin/’
3b. //* File names based on date this JCL starts (or restarts)
//* The variable Q allows mixed case to be used in other variables
// SET Q=’’’’
// SET INSTDIR=’/’
// SET CTGDIR=&Q.&INSTDIR.bin/&Q.
// SET LOGDIR=&Q.&INSTDIR.logs/&Q.
// SET CTGLOG=&Q.&LOGDIR.&CTGNAME.o.&YYMMDD..log&Q.
// SET CTGERR=&Q.&LOGDIR.&CTGNAME.e.&YYMMDD..log&Q.
Chapter 8. Operation 121

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Operation
Table 7. Sample JCL to register the Gateway with ARM and start it as a batch
job (continued)
Stage Code
4. //TIMESTMP EXEC PGM=BPXBATCH,
// PARM=’SH echo Starting &CTGNAME. on $(date)’
//STDOUT DD PATH=’&CTGLOG.’,
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU
5. //REG EXEC PGM=BPXBATCH,
// PARM=’PGM &CTGDIR.ctgarm REGISTER &CTGNAME.’
//STDOUT DD PATH=’&CTGLOG.’,
//
//*
PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU
// IF RC < 5 THEN
6. //CTG EXEC PGM=BPXBATCH,
// PARM=’SH &CTGDIR.ctgstart -noinput’,
// REGION=8M
//STDOUT DD PATH=’&CTGLOG.’,
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU
//STDERR DD PATH=’&CTGERR.’,
//
//*
PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU
7. //DEREG EXEC PGM=BPXBATCH,
// PARM=’PGM &CTGDIR.ctgarm DEREGISTER’
//STDOUT DD PATH=’&CTGLOG.’,
//
// ENDIF
PATHOPTS=(OWRONLY,OCREAT,OAPPEND),PATHMODE=SIRWXU
8. //
Stages:
1. Include this stage.
2. Choose one of the following stages to identify the JCL run:
a. If you are not using ARM, any name is acceptable.
b. If you are using ARM, the name must be unique across the sysplex.
3. Choose one of the following stages to define the log files:
a. This stage uses a fixed name for the log files. Messages are written to
the same files whenever the JCL is run. Stage 4 on page 123 tells you
how to overwrite the files, or append messages to them.
b. In this stage, the log file names include the date on which the JCL was
run. Unique log files are created for each day on which the JCL is run.
If you run the JCL more than once a day, messages are written to the
log files from the first run.
122 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Operation
Consider setting the location of the CICS Transaction Gateway trace file to
the same location. Make an entry like the following in the Gateway section
of the CTG.INI file:
tfile=/logs/ctg.trace
4. TIMESTMP enters the date and time into the standard output log file STDOUT.
With the OAPPEND option specified in PATHOPTS, ARM and the CICS
Transaction Gateway append messages to the existing log file. To
overwrite the log file at each restart, remove the OAPPEND option from
PATHOPTS.
5. This stage registers your CICS Transaction Gateway with ARM; omit it if
you do not wish to use ARM. BPXBATCH is the MVS program that runs a
z/OS UNIX System Services script as a batch job.
6. This stage starts the Gateway daemon. The PARM field specifies that the
shell, SH, runs the ctgstart command with the -noinput option. To reduce
the number of messages written to the standard output log file, do not
select the gateway setting Log client connections and disconnections. See “Log
client connections and disconnections” on page 58 for more information.
The OAPPEND option in PATHOPTS causes the CICS Transaction Gateway to
append messages to existing log files.
7. This stage deregisters the Gateway with ARM. It is only called if the
Gateway is closed down correctly. Omit this stage if you do not wish to
use ARM.
8. End of job.
Note: When the CICS Transaction Gateway is started with JCL, a number of
other jobs are started in addition to the specified job. For example, for a
jobname CICSTGQ, there would also be a number of jobs named
CICSTGQ1 through CICSTGQn.
If the JCL terminates unexpectedly
If the JCL terminates immediately, and diagnosis of the JCL output shows that
ctgstart terminated, examine file STDERR for details of why ctgstart failed.
Region size considerations
Set the REGION parameter on the EXEC card in the JCL according to the
number of threads that the CICS Transaction Gateway will run.
The following parameters might also affect the values that you can choose for
the REGION parameter.
v The ASSIZEMAX parameter of the OMVS segment of a RACF userid; see
the RACF Command Language Reference for more information.
v The UNIX System Services MAXASSIZE parameter found in
SYS1.PARMLIB(BPXPRMxx); see the UNIX System Services Planning book for
more information.
Chapter 8. Operation 123

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Operation
The value specified for ASSIZEMAX overrides any value provided by the
MAXASSIZE parameter
Note: A setting of REGION=0M may cause a java.lang.OutOfMemoryError;
see “java.lang.OutOfMemory exception” on page 143.
Starting multiple CICS Transaction Gateways
See /samples/samples.txt for details of sample JCL provided.
To start multiple copies of the CICS Transaction Gateway requires a separate
CTG.INI file for each one; see “The environment variables” on page 48 for
details of how to do this using the CICSCLI environment variable.
The following example shows you how to start multiple copies of the CICS
Transaction Gateway using a started task. Run the example as a job:
//CTG24 JOB CLASS=A
/*JOBPARM SYSAFF=P24
// COMMAND ’S CTG,JOBNAME=CTGT2401,ID=01,SYSID=T24A’
// COMMAND ’S CTG,JOBNAME=CTGT2402,ID=02,SYSID=T24A’
// COMMAND ’S CTG,JOBNAME=CTGT2403,ID=01,SYSID=T24B’
// COMMAND ’S CTG,JOBNAME=CTGT2404,ID=02,SYSID=T24B’
// EXEC PGM=IEFBR14
Each Gateway running on the sysplex must have a unique ID.
This starts the following JCL for each CICS Transaction Gateway. The job is
shown here as a series of stages so that you can modify it if you do not wish
to use ARM. Code the job in the normal way; do not include the entries in the
Stage column.
Table 8. Sample JCL to register the Gateway with ARM and start it as a batch job
Stage Code
1. //CTG PROC ID=’01’,SYSID=’T24A’
//*
//*ID -UNIQUE ID FOR THIS INSTANCE OF THE CTG
//*
//* The variable Q allows mixed case to be used in other variables
// SET Q=’’’’
2a. //* Name to identify this JCL run
// SET CTGNAME=’CTG’
2b. //* Unique ID for ARM and used to identify this JCL run
// SET CTGNAME=&Q.CTGARM_&SYSID.&ID.&Q.
124 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Table 8. Sample JCL to register the Gateway with ARM and start it as a batch
job (continued)
Stage Code
3a. //* Fixed file names for log files
// SET CTGLOG=&Q./logs/CTG&SYSID.&ID.o.log&Q.
// SET CTGERR=&Q./logs/CTG&SYSID.&ID.e.log&Q.
// SET CTGDIR=&Q./bin/&Q.
// SET CTGENV=&Q./bin/ctgenv&SYSID.&ID.&Q.
3b. //* File names based on date this JCL starts (or restarts)
// SET INSTDIR=’/’
// SET CTGDIR=&Q.&INSTDIR.bin/&Q.
// SET LOGDIR=&Q.&INSTDIR.logs/&Q.
// SET CTGLOG=&Q.&LOGDIR.&CTGNAME.&SYSID.&ID.o.&YYMMDD..log&Q.
// SET CTGERR=&Q.&LOGDIR.&CTGNAME.&SYSID.&ID.e.&YYMMDD..log&Q.
// SET CTGENV=&Q.&CTGDIR.ctgenv&SYSID.&ID.&Q.
4. //TIMESTMP EXEC PGM=BPXBATCH,
// PARM=’SH echo Starting &CTGNAME. on $(date)’
//STDOUT DD PATH=’&CTGLOG.’,
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),
// PATHMODE=(SIRWXU,SIRWXG,SIRWXO)
5. //REG EXEC PGM=BPXBATCH,
// PARM=’PGM &CTGDIR.ctgarm REGISTER &CTGNAME.’
//STDOUT DD PATH=’&CTGLOG.’,
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),
//
//*
PATHMODE=(SIRWXU,SIRWXG,SIRWXO)
// IF RC < 5 THEN
6. //CTG EXEC PGM=BPXBATCH,
// PARM=’SH &CTGDIR.ctgstart -noinput’,
// REGION=8M
//STDOUT DD PATH=’&CTGLOG.’,
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),
// PATHMODE=(SIRWXU,SIRWXG,SIRWXO)
//STDERR DD PATH=’&CTGERR.’,
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),
// PATHMODE=(SIRWXU,SIRWXG,SIRWXO)
//*SETERR DD PATH=’/dev/null’
//STDENV DD PATH=’&CTGENV.’,
//
//*
PATHOPTS=(ORDONLY)
7. //DEREG EXEC PGM=BPXBATCH,
// PARM=’PGM &CTGDIR.ctgarm DEREGISTER’
//STDOUT DD PATH=’&CTGLOG.’,
// PATHOPTS=(OWRONLY,OCREAT,OAPPEND),
//
// ENDIF
PATHMODE=(SIRWXU,SIRWXG,SIRWXO)
Operation
Chapter 8. Operation 125

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Operation
Table 8. Sample JCL to register the Gateway with ARM and start it as a batch
job (continued)
Stage Code
8. //PEND
//
Stages:
1. Include this stage.
2. Choose one of the following stages to identify the JCL run:
a. If you are not using ARM, any name is acceptable.
b. If you are using ARM, the name must be unique across the sysplex.
3. Choose one of the following stages to define the log files:
a. This stage uses fixed names for the log files; messages are written to
the same files whenever the JCL is run. The name of the CICS
Transaction Gateway is used in the log file name, so it is clear which
log belongs to which CICS Transaction Gateway. If you adopt a similar
convention it should always be possible to identify which messages
belong to which CICS Transaction Gateway.
b. In this stage, the log file names include the date on which the JCL was
run. Unique log files are created for each day on which the JCL is run.
If you run the JCL more than once a day, messages are written to the
log files from the first run.
4. TIMESTMP enters the date and time into the STDOUT log.
5. This stage registers your CICS Transaction Gateway with ARM. Omit it if
you do not wish to use ARM.
6. This stage starts the Gateway daemon.
7. This stage deregisters the Gateway daemon with ARM. It is called only if
the Gateway daemon is closed down correctly. Omit this stage if you do
not wish to use ARM.
8. End of procedure.
Note the changes for PATHMODE and PATHOPTS compared to the JCL for a
single CICS Transaction Gateway instance. Without these you have to have
the same userid as that under which the jobs run, or have superuser authority
to read the log files. Also, coding STDERR to /dev/null results in no trace file
being written. This is necessary as you cannot stop the connect/disconnect
trace entries going to STDERR. The commented out definition of STDERR is
provided as an example of this alternative.
The above JCL also pulls in a unique STDENV data set for each instance of
the CICS Transaction Gateway. You also need to change ctgstart to avoid
126 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
modifying or overwriting STEPLIB for this STEPLIB definition to take place.
This is an example file /bin/ctgenvT24A01:
DFHJVPIPE=BATCHCLI
DFHJVSYSTEM_00=CICST24A
DFHJVSYSTEM_01=CICST24B
DFHJVSYSTEM_02=CICST25A
DFHJVSYSTEM_03=CICST25B
STEPLIB=CICSTS22.SDFHEXCI:CICSTS22.SDFHLOAD
CICSCLI=/bin/CTGT24A01.INI
Operation
Each of the other three instances of the Gateway in the started task example
would have its STDENV file (T24A02, T24B01 and T24B02). Each of these files
would reference a separate CTG.INI file through the CICSCLI environment
variable, to define a minimum of a unique TCP/IP port number.
If you are using TCP/IP port sharing as a form of workload management in
an MVS image, consider using port 2006 (the default) for each CICS
Transaction Gateway.
To allow the client the freedom of not specifying a specific CICS APPLID on
the incoming request, modify the DFHXCURM sample by removing the
branch in the sample and code giving it a list of the CICS regions. One
DFHXCURM exit is needed for each CICS region. As you cannot change the
name of the exit, place the exit into unique Partitioned Data Sets and ensure
they are placed first in the STEPLIB environment variable (in the above file).
To start multiple CICS Transaction Gateways from OMVS with console input
when directed to a port that is portshared, define the jobname ″OMVS″ as
having access to the shared port in the TCP/IP profile. If console input is not
required, then start the CICS Transaction Gateways via JCL and define the JCL
jobname in the TCPIP profile.
See “EDC5111I PERMISSION DENIED message” on page 139, for information
on a problem that can be caused when the CICS Transaction Gateway
jobname is shorter than eight characters.
Stopping the CICS Transaction Gateway
If you started the CICS Transaction Gateway from the command line, and if
you did not specify the -noinput parameter, you can stop the Gateway by
typing Q and pressing Enter in the Gateway console session.
If you have used the -noinput parameter, or if you used JCL to start the CICS
Transaction Gateway, you must stop the Gateway process by using the JES
CANCEL command.
Chapter 8. Operation 127

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Operation
Note: When you cancel the main CICS Transaction Gateway job, all other jobs
are cancelled. For example, for a jobname CICSTGQ, the jobs named
CICSTGQ1 through CICSTGQn would also be cancelled.
Administering your system
If you enabled the TCPAdmin protocol (see “TCPAdmin protocol settings” on
page 62), you can perform the following administrative functions without
having to restart the CICS Transaction Gateway:
v Set the Gateway trace
v Set JNI trace
v Query the current trace settings
You execute the Java archive ctgadmin.jar from a command prompt to set
trace or to query trace settings. You can administer the CICS Transaction
Gateway remotely from a workstation that has this JAR file and the supported
level of Java; you do not need to install the CICS Transaction Gateway on the
workstation. See “TCPAdmin protocol settings” on page 62 for details of how
to define which hosts have permission to administer your CICS Transaction
Gateway.
The following sections describe the commands. Parameters are not case
sensitive; those in brackets are optional.
Warning: Do not specify a CICS Transaction Gateway earlier than version 5.0.
Earlier versions cause the administration program to lock. If this
happens, terminate the process, for example by pressing Ctrl+C.
Setting the Gateway trace
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address -a=setgwtrace [-tfile=path]
[-tfilesize=number] [-tlevel=number]
[[-truncationsize=number][-dumpoffset=number]|-fulldatadump]
See “Parameters” on page 129 for an explanation of parameters.
Setting the JNI trace
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address
-a=setjnitrace -tfile=path [-tlevel=number]
See “Parameters” on page 129 for an explanation of parameters.
Querying trace settings
From a command prompt, issue the following command:
java -jar ctgadmin.jar -ctg=address -a=qtrace
128 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Parameters
See “Parameters” for an explanation of parameters.
Administering your system
ctg Mandatory. Specifies the Gateway which is to be
administered. You can specify either a hostname, for example
tcp://myserver:2810, or an IP address, for example
tcp://127.0.0.1:2810. In these examples, 2810 is the port you
specified for TCPAdmin; see “TCPAdmin protocol settings” on
page 62.
Warning: Do not specify a CICS Transaction Gateway earlier
than version 5.0. Earlier versions cause the
administration program to lock. If this happens,
terminate the process, for example by pressing
Ctrl+C.
a Mandatory. Defines the action to take. Permitted values are:
v setgwtrace to control Gateway tracing
v setjnitrace to control JNI tracing
v qtrace to determine what trace settings are active
tfile Specifies the output file for Gateway or JNI tracing, for
example ./tracefile.trc. Do not specify the same file for
Gateway and JNI trace output.
Gateway tracing
If you do not specify a value for this tag, trace output is
sent to the console.
JNI tracing
You must specify a value for this tag. If you do not, an
error is displayed.
tlevel Specifies the trace level. Permitted values are:
Gateway tracing:
0 Off. No trace information is output.
1 Exception tracing. Only exceptions are traced.
Equivalent to ctgstart -stack; see “Starting the
Gateway with user-specified options” on page 117.
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).
Chapter 8. Operation 129

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Administering your system
JNI tracing:
0 Off. No trace information is output.
1 On.
tfilesize Specifies the maximum size, in kilobytes, of the trace output
file, for example 50000.
dumpoffset 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. You
cannot use this together with the fulldatadump parameter.
truncationsize 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 parameter.
fulldatadump Sets the dumpoffset to 0 and ignores any value specified in
truncationsize.
130 CICS Transaction Gateway: z/OS Administration

Chapter 9. Problem determination
Preliminary checks
What to do next
Problem determination is not to be confused with problem solving, although
while investigating a problem you may find enough information to solve the
problem. Examples of the types of problem that can arise are:
v End-user errors
v Programming errors
v Configuration errors.
Before investigating the problem, it is worth checking to see whether there is
an obvious cause:
v Has the system run successfully before?
v Have you made any changes to the configuration of the system or added
new features or programs?
v If you have migrated from CICS Transaction Gateway for OS/390 Version 3,
are you sure that the configuration file (Gateway.properties), and JGate
script were migrated successfully?
v Are your environment variables, such as CLASSPATH and LIBPATH set
correctly? (See “Setting environment variables” on page 47.)
The CLASSPATH variable is displayed at the top of the CICS Transaction
Gateway trace output. See “Tracing” on page 133 for information on starting
the Gateway with tracing enabled.
v Are there any messages explaining the failure?
See “Messages” on page 132.
v Can the failure be reproduced?
If you think the problem is with the CICS Transaction Gateway, see
“Diagnosing common problems” on page 139. 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 149 for information on how to contact IBM.
See “Documenting problems” on page 150 for the information that you will be
asked to provide.
© Copyright IBM Corp. 1996, 2002 131

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
CICS Transaction Gateway for z/OS problem determination
Messages
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.
The Gateway daemon writes log messages to standard output (stdout) orto
standard error (stderr). If Gateway daemon tracing is enabled, it also writes
log messages to the trace output file.
Messages have the format:
CCLnnnnt:
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
See “Starting with JCL” on page 121 for examples of redirecting standard
output and standard error to files. You can choose to redirect both standard
output and standard error to the same file.
Refer to the documentation for your operating system for more information
on redirecting output.
See CICS Transaction Gateway: Gateway Messages for an explanation of all CICS
Transaction Gateway messages.
Sources of information
You can get problem determination information from the following sources:
v The standard output (stdout) and standard error (stderr) files. As well as
CICS Transaction Gateway messages (see “Messages”), these files also
contain other messages as follows:
– Standard output contains any messages returned to EXCI from CICS.
– Standard error contains error messages from the Java virtual machine
(JVM). The JVM messages are documented in the Java development
toolkit (JDK).
v CICS Transaction Gateway trace, see the following section.
v EXCI trace: This shows the EXCI activity. A CICS Transaction Gateway trace
is part of the EXCI trace and the trace points are listed in Table 9 on
page 137. For details of EXCI tracing, see the CICS External Interfaces Guide
132 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
Tracing
CICS Transaction Gateway for z/OS problem determination
v JNI log: check file ctgjnilog. for JNI error codes. The location
of the file is as follows:
– Normally in /ibm/ctg, where is the
directory defined in the user’s $HOME environment variable.
– If the $HOME environment variable is not set, the log file is written to
the user’s current directory.
If the CICS Transaction Gateway does not have the necessary write
permission, the log is not created.
See CICS Transaction Gateway: Gateway Messages for an explanation of the
codes.
v CICS trace: This shows the progress of the request through:
– The CICS mirror transaction that handles the EXCI request
– The called CICS program.
Examine the AP trace points in the CICS trace.
To route messages and trace information to a file, specify:
ctgstart -trace -tfile=pathname
when starting the Gateway, which generates a file in the pathname directory.
To produce a full debug trace, you can use the ctgstart -x option.
There are three main levels of Gateway 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.
Standard tracing Java exceptions and the main Gateway
functions and events are traced. By default,
the Gateway 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
functions and events are traced in greater
detail than with stack or standard tracing. By
default, the Gateway displays the whole of
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 9. Problem determination 133

CICS Transaction Gateway for z/OS problem determination
Gateway tracing
You can start tracing in the CICS Transaction Gateway process, or in the user
application that makes calls to the Gateway.
You use options on the ctgstart command to enable and control tracing in the
Gateway. For example, to enable the standard trace, type the following
command when starting the Gateway:
ctgstart -trace
If you used the configuration tool to configure your Gateway, (or set the
TFILE parameter in the CTG.INI file), then the default destination for trace
output is file ctg.trc in the /bin subdirectory. 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 with debug tracing enabled and writes the trace output to
the file specified by pathname.
The options you can specify on ctgstart are:
-trace
Enables standard tracing. It only traces the first 80 bytes of the
COMMAREA by default.
-stack
Enables exception stack tracing only. Most Java exceptions are traced,
including exceptions that are expected during normal operation of the
CICS Transaction Gateway, but no other tracing is done.
-x Enables full debug tracing. This includes everything traced by the -trace
option, plus additional information including information about the
internal workings of the CICS Transaction Gateway. This option traces the
entire COMMAREA by default.
This option will decrease performance significantly.
-tfile=pathname
If tracing is enabled, writes the trace messages to the file specified in
pathname. This overrides the default destination for trace output (see the
-trace option).
-tfilesize=number
Specifies the maximum size, in kilobytes, of the trace file.
-truncationsize=nnn
Specifies the maximum size of any data blocks shown in the trace, where
nnn is any positive integer. You can use this option in addition to either
134 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
CICS Transaction Gateway for z/OS problem determination
-trace or -X and this overrides the default size set by these options. For
example, to switch on standard tracing and dump a maximum of 20,000
bytes:
ctgstart -trace -truncationsize=20000
If you specify a value of 0, no data blocks are shown in the trace.
-dumpoffset=offset
Specifies the offset from which displays of any data blocks start. If the
specified offset is greater than the total length of data, the data is dumped
as if the offset were 0.
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 also written to stderr if you use 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.
Time stamps
If the time stamps in console messages and trace files are approximately 20
seconds different from the system clock, apply IBM Java APAR PQ47736. This
APAR is recommended if you are using CICS Transaction Gateway tracing. It
is available in Java PTF UQ56153 (included in Service Refresh 9).
Application tracing
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 comprises several static methods in the T class of
the CICS Transaction Gateway. See the CICS Transaction Gateway: Programming
Guide book for further information.
JNI tracing
You cannot enable JNI trace through the configuration tool. Use one of the
following methods to enable it:
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.
Chapter 9. Problem determination 135

|
|
|
|
|
|
|
|
|
|
|
|
|
|
CICS Transaction Gateway for z/OS problem determination
v While the CICS Transaction Gateway is running, use the system
administration functions. You must have enabled the TCPAdmin protocol
handler (see “TCPAdmin protocol settings” on page 62). See “Administering
your system” on page 128 for details of how to enable JNI trace
dynamically.
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
Using the CTG_JNI_TRACE environment variable to enable JNI trace is
supported only for migration purposes.
To obtain a JNI trace for a local mode connection from a servlet under
WebSphere Application Server, do the following:
1. Set CTG_JNI_TRACE=filename in the httpd.envvars file
2. Modify the IHS JCL to specify parameters to the Language Environments
(LE) as follows:
LEPARM=’ENVAR("_CEE_ENVFILE=/your/httpd.envvars")’
3. Ensure the user ID under which WebSphere Application Server is running
has write permission to the trace output file.
For more information refer to the WebSphere Application Server
documentation.
J2EE Tracing
Refer to “Tracing” on page 71 for information on using the tracing function
provided with the ECI and EPI resource adapters.
Issues with tracing if ConnectionFactory serialized
As described above, if you use the serializable interface to store your
ConnectionFactory then you lose the reference to your LogWriter. This is
because LogWriters are not serializable and cannot be stored. When you
deserialize your ConnectionFactory it will not contain a reference to the
LogWriter. To ensure that your LogWriters are stored on any connections
created from this ConnectionFactory you must do the following. This only
applies in a nonmanaged environment.
DefaultConnectionManager.setLogWriter(new java.io.PrintWriter(System.err));
Connection Conn = (Connection)cxf.getConnection();
136 CICS Transaction Gateway: z/OS Administration

The setLogWriter method on the DefaultConnectionManager, which is
supplied with the resource adapters, is a static method. The example above
shows how to set the log to output the System.err. The trace level applied to
the ManagedConnectionFactory remains.
EXCI trace
The CICS Transaction Gateway writes trace entries to the EXCI trace. The
trace entries are in the CICS trace EXCI format, so the trace entries in a dump
can be printed using standard z/OS utilities. You can use the following
operating procedure from the SDSF operator console:
1. Use the command
/D OMVS,A=ALL
CICS Transaction Gateway for z/OS problem determination
to display OMVS tasks.
2. Find the CICS Transaction Gateway task, and note the ASID.
3. Enter the DUMP command with a suitable comment. For example:
/DUMP COMM=(JGATE DUMP)
4. Reply to the message with the ASID as follows:
/R nn,ASID=aa,END
where nn is the message number for the reply, and aa is the ASID.
Table 9 shows the trace points written to the EXCI trace by the CICS
Transaction Gateway.
Table 9. EXCI trace points for the CICS Transaction Gateway
Point ID Module Lvl Type Data
8000 JVDLL EX 1 ECI parameters passed 1 Thread name
2 Call_Type
3 Extend_Mode
4 Luw_Token
5 Commarea_Length
6 Cics_Rc
7 Message_Qualifier
8001 JVDLL Exc GetStringPlatform error 1 Return code
2 Data area
3 Length
8002 JVDLL Exc GetStringPlatformLength
error
1 Return code
8003 JVDLL EX 1 Converted parameter 1 Thread name
2 Parameter name
3 Parameter value
Chapter 9. Problem determination 137

CICS Transaction Gateway for z/OS problem determination
Table 9. EXCI trace points for the CICS Transaction Gateway (continued)
Point ID Module Lvl Type Data
8004 JVDLL EX 1 Inbound COMMAREA 1 Thread name
2 Communication
area length
3 Communication
area address
4 250 bytes of data
8006 JVDLL EX 1 Outbound COMMAREA 1 Thread name
2 Communication
area length
3 Communication
area address
4 250 bytes of data
8007 JVDLL EX 1 ECI parameters output 1 Thread name
2 Call_Type
3 Extend_Mode
4 Luw_Token
5 Commarea_Length
6 Cics_Rc
7 Message_Qualifier
8010 JVDLL Exc Error response received 1 Function number
2 EXCI response
3 EXCI reason
4 EXCI subreason
field-1
5 EXCI subreason
field-2
6 Cics_Rc
8011 JVDLL Exc DPL_REQUEST error 1 RESP
2 RESP2
3 ABCODE
4 Cics_Rc
8012 JVDLL Exc WBA1 parameters 1 malloc length
allocation error
2 Cics_Rc
8013 JVDLL Exc Invalid call type 1 Thread name
2 Call_Type
3 Cics_Rc
8014 JVDLL Exc Invalid COMMAREA 1 Thread name
length
2 Commarea_Length
3 Size of Commarea
4 Cics_Rc
138 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems
Installation
During installation, you might see messages indicating that files are missing
or corrupt:
Phase 1 of 6 complete,
Phase 2 of 6 complete,
FSUM8746 line 205726: Line too short (44 bytes, expecting 62)
Phase 3 of 6 complete,
uncompress: ctg.tar.Z: FSUM6639 compressed file is corrupt
Phase 4 of 6 complete,
tar: opening archive "ctg.tar": EDC5129I No such file or directory.
rm: FSUM9195 cannot unlink entry "ctg.tar": EDC5129I No such file or directory.
Phase 5 of 6 complete,
chmod: FSUM6188 stat file "ctg": EDC5129I No such file or directory.
Phase 6 of 6 complete.
CICS Transaction Gateway installed.
This indicates that there is insufficient space in the /tmp directory. Either clear
out the directory, or increase it to the minimum recommended size; see “Disk
space requirements” on page 19.
The configuration tool
Diagnosing common problems
The Gateway daemon fails to find Turkish configuration settings
When you run the configuration tool under a Turkish locale for the first
time, by default the configuration settings are saved in file CTG.INI.ini.
Rename the file to CTG.INI to allow the Gateway daemon to find the
settings automatically. You only have to do this once, when the
configuration tool is first run.
Known limitations
v On startup, the configuration tool displays a color exception.
v The tool can read a configuration file only if it has fewer than 65
servers.
v USS does not fully support DBCS in graphical user interfaces. Until a
solution is found run the tool in English:
ctgcfg -LANG US
EDC5111I PERMISSION DENIED message
This message can be generated because:
v A CICS Transaction Gateway port is already in use by another task.
v A port is reserved for the CICS Transaction Gateway job in the
TCPIP.PROFILE, but the CICS Transaction Gateway jobname is less than 8
characters. In this case the job that attempts to open the port will have a
jobname with a numeric suffix allocated by UNIX System Services and will
not match the TCPIP.PROFILE jobname. To solve this problem:
Chapter 9. Problem determination 139

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems
1. Do not reserve the port
2. Use an eight character jobname
3. Add ’OMVS’ to the list of IDs allocated the port in the TCPIP.PROFILE.
It is not advisable to anticipate the numeric character added by UNIX
System Services as an ID.
CEE3250C ABEND S806 message
The following message might be received when starting the Gateway if the
Userid does not have sufficient authority to access the system product and
load libraries:
CEE3250C The system or user abend S806 R=00000004 was issued.
From entry point MVS_CcicsInit at compile unit offset -FFFF8D84
at address 1AEB158C.
The message is also displayed if the STEPLIB variable does not point to the
correct CICS EXCI load library, see “The environment variables” on page 48
for more information.
Multiple Address Spaces
When running the CICS Transaction Gateway, two address spaces may be
used. One is used for the ctgstart shell script, and the other for the Java
Virtual Machine containing the CTG. Some users may consider this to be
undesirable.
Take the following actions to resolve the situation:
v Place the follwing two variables in the JCL:
_BPX_SHAREAS=YES
_BPX_SPAWN_SCRIPT=YES
v Ensure that all the CICS Transaction Gateway’s files have the extended
attribute ’s’ set:
1. To display the extended attributes for files, use ls -E
2. To set the ’s’ attribute on files use the extattr +s command
Note: If you wish to use the CTG’s support for RACF user/password
authentication, the JVM which the CICS Transaction Gateway runs in
MUST be in it’s own address space.
Automatic Restart Manager (ARM) problems
Different region used following a restart
When ARM tries to restart a job after a failure, it uses any suitable region.
This might be a different region to that in which you started CICS Transaction
Gateway. If you are not running with TCP/IP port sharing, so that the shared
port is routed to whichever region is up and supporting that port number,
140 CICS Transaction Gateway: z/OS Administration

|
|
|
|
Diagnosing common problems
when the JCL restarts on a new MVS image it has a new URL and address. To
avoid this, modify the ARM profile for the ARM_ID you are using so that it
restarts only in the same region.
For more information, see z/OSV1R2.0 MVS Setting up a Sysplex, SA22–7625.
Conflicts with default ports
The CICS Transaction Gateway uses default ports for its supported protocols.
These may conflict with ports already in use, and if this is the case, one or
more protocols fail to start successfully. You can change port number in the
CTG.INI file, see “Using the configuration tool” on page 52.
EXCI pipe limitations
You may experience problems due to EXCI pipe limitations when using
servlets when running CICS Transaction Gateway in local mode.
A single z/OS address space is limited by CICS interregion communication
(IRC) to allocating a maximum of 100 EXCI pipes to all attached CICS regions.
In contrast, the maximum pipe usage in a CICS region is limited only by the
number of sessions defined in the CICS multiregion operation (MRO) sessions
definition, which can specify up to 999. Thus the following limitations apply
to the use of the EXCI by the CICS Transaction Gateway from a servlet:
v The Web server directive MaxActiveThreads sets the maximum number of
concurrent requests that can be serviced. This is not the same as the
maximum number of users, because the z/OS Web server will queue
requests to use threads, according to the setting of the TCP/IP
SOMAXCONN parameter or the Web server ListenBackLog directive.
v Each thread that services an ECI request will allocate an EXCI pipe, and
this pipe remains allocated until either a failure occurs or the CICS MRO
connection is terminated. Such pipes is used by subsequent requests to the
servlet. Pipes however, cannot be shared across different Web server
threads.
v If the number of threads using the CICS Transaction Gateway exceeds 100,
the 101st EXCI Allocate_Pipe call fails with a SYSTEM_ERROR response
code, and a reason code 608. The ECI application receives a return code -9
(ECI_ERR_SYSTEM_ERROR). This means a limitation in the sending
address space has been reached, therefore you should consider configuring
MaxActiveThreads in your Web server to be less than or equal to 100.
v If the CICS Transaction Gateway tries to allocate more pipes than there are
available sessions defined in the CICS sessions definition, the EXCI
Open_Pipe call fails with a RETRYABLE response code, and a reason code
202. The ECI application receives a return code -16
(ECI_ERR_SYSTEM_ERROR) and DFHXCURM is invoked. In this case,
Chapter 9. Problem determination 141

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems
consider setting the RECEIVECOUNT parameter in the CICS sessions to at
least 100. For more information, refer to “CICS server sessions definition”
on page 40.
v Applids are specified in EXCI calls. The EXCI user exit can change an
applid, but does not affect the number of pipes allocated. Unless the 100
pipe limit has been reached, the number of pipes allocated on a thread
depends only on the number of unique applids as specified in the EXCI
requests.
If the requests are non-extended, and have no affinity to the region in
which they will run, the user exit can distribute them across regions. To do
this, specify the same dummy applid on all requests, and write a user exit
that redirects requests to the required applid. If you do not use a single
dummy applid, the maximum number of concurrent transactions may be
reduced when the user exit runs. For example, if some requests come in
with applid1 and some with applid2, the maximum number of concurrent
transactions that can run is 100 /2=50.(For n applids the formula is
100/n.) This is because each thread could have two allocated pipes (one for
applid1 and one for applid2). Since EXCI requests are synchronous, each
thread can use only one of its two pipes, and the maximum number of
concurrent transactions is halved. This is true in:
– local mode when the thread issuing the EXCI calls is the java application
thread
– remote mode where the EXCI requests are issued by worker threads
v If you discover that you require more than 100 threads in your Web server,
it is recommended that you balance workload across Web servers using
TCP/IP port sharing, or use the Web server in scalable mode, which allows
the usage of multiple HTTP Q server address spaces (each of which can use
100 pipes with the CICS Transaction Gateway).
Java exceptions
If the application or the CICS Transaction Gateway does not handle an
exception, then the Java Virtual Machine (JVM) writes 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 16 on page 143 shows a sample Java stack dump taken with the JIT
compiler disabled.
142 CICS Transaction Gateway: z/OS Administration

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 16. Sample Java stack dump
Diagnosing common problems
If the CICS Transaction Gateway handles an exception, a Java stack dump is
written only if tracing is enabled. Try to reproduce the problem with tracing
enabled. This should help to show you what was happening before the
exception occurred. See “Tracing” on page 133 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:
CCL6664E: 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.lang.OutOfMemory exception
If this happens after the CICS Transaction Gateway has been running for a
long time, then it could be caused by a memory leak. If it happens only when
the Gateway is heavily loaded, then there might be too many threads active
for the available Java Virtual Machine (JVM) memory.
Memory leak
Run a memory usage monitor against the Gateway process. If there is a
memory leak, the amount of memory used by the Gateway increases over
time. Make sure that all user applications that connect to the CICS Transaction
Gateway close the JavaGateway() connection object when they have finished
using it. If this does not resolve the problem, run the Gateway 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.
Chapter 9. Problem determination 143

Diagnosing common problems
Too many threads
These symptoms may be caused by:
1. The BPXPRMxx value for MAXTHREADS being reached. The solution is
to increase the value of MAXTHREADS. For more information, see “The
CICS Transaction Gateway: threading model” on page 14.
2. Use of REGION=0M in the CICS Transaction Gateway startup JCL. The
actual region size available when 0M is used is unpredictable and may be
less than required for the number of threads being run by the CICS
Transaction Gateway. The solution is to allocate an explicit region size.
This value is dependent on the number of threads required to be run by
the CICS Transaction Gateway (see “Region size considerations” on
page 123.)
3. Use of the JVM default stack size values -ss (256 KB) and -oss (400 KB),
which results in a memory allocation of 656 KB per thread. Halving these
values on the exec java statement in the ctgstart script reduces memory
consumption.
You can estimate the amount of virtual memory that is required by the JVM
as follows. Add together:
v the number of Connection Manager threads
v the number of Worker threads
v the number of background threads in use by Java
v the number of different network protocols in use
Then multiply this total by the size of the Java stack allocated to each thread
by the JVM.
In this calculation, assume that the number of active Java background threads
is about five. Refer to your Java documentation for a more accurate value. You
set the maximum numbers of Connection Manager threads and Worker
threads in the configuration of your CICS Transaction Gateway. See “General
Gateway settings” on page 56 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 amount of memory available to the JVM by using the java -mx
option.
v Set the amount of memory that Java allocates to each thread by using the
java -oss and java -ss options. The size of the Java stack is the sum of these
two values..
For more information on thread limits see Table 3 on page 15. For more
information on Java memory allocation refer to the CICS Transaction Gateway:
Programming Guide book and to your Java documentation.
144 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
On z/OS systems, the amount of memory available to each process might be
limited. See your operating system documentation for more information.
Authorization failure using servlets with WebSphere
Servlets that use the WebSphere autostart function do not have the required
authority to access CICS Transaction Gateway. The following message appears
in the JNI trace:
CcicsECI: Authorise userid/password with RACF. Return code = -1, errno = 157
If this happens, use user-driven servlets, where the initialization is performed
in the servlet’s init() method.
If a process locks
To determine where the lock is happening, enable tracing in the application,
and in the Gateway, see “Tracing” on page 133. If the lock is in the Gateway,
contact your IBM support organization and provide them with the Gateway
trace.
On some Java Virtual Machine (JVM)s, including the z/OS JVM, you can force
Java to write a stack trace showing the states of the current threads. For
example, on IBM Java SDK 1.3.1 you can send a SIGQUIT (-3) signal to a
Java process to make it write a stack trace 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.
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
variable. If this does not give you enough information to diagnose the
problem, obtain a standard trace and contact your IBM support organization.
SSLight
Diagnosing common problems
When starting the CICS Transaction Gateway: The following message is
issued when starting the Gateway:
CCL6525W: Unable to start handler for the ssl: protocol.
[java.lang.ClassNotFoundException:
server KeyRing class name]
This message shows that the Gateway could not load the server KeyRing
class. Start the Gateway with stack tracing enabled. Check that the
CLASSPATH variable, which is displayed at the top of the trace output,
includes an entry for the directory that contains the class. Also check that the
Chapter 9. Problem determination 145

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Diagnosing common problems
CLASSPATH includes an entry for file cfwk.zip. If the Gateway cannot find
this file, it cannot load the KeyRing files.
You specify the name of the server KeyRing class in the KeyRing classname
field in the SSL protocol settings panel in the configuration tool. Do not
include the directory or file extension when you specify the KeyRing class
name. The CLASSPATH should include an entry for the directory that
contains the KeyRing class.
In a user application: The API call
SslJavaGateway.setKeyRing("ClientKeyRingName", "thePassword"); fails with
the following error in a user application:
java.lang.NoClassDefFoundError: com/ibm/sslight/SSLightKeyRing
Check that the CLASSPATH variable includes an entry for file cfwk.zip. This
file is supplied with the CICS Transaction Gateway.
JSSE
JSSE assumed when using SSLight: If you pass a KeyRing or Keystore
name to CICS Transaction Gateway, but the class does not load, or cannot be
found, the Gateway daemon assumes that you are using JSSE and not
SSLight.
iKeyMan locks with ″class not found″ exception: A message like the
following is received by the application:
java.lang.NoClassDefFoundError: com/ibm/security/pkcsutil/PKCSException
This happens if the IBM Java Cryptography Extension (JCE) package is not
installed. Ensure that you have installed the JCE supplied with CICS
Transaction Gateway in the ibm-jce.zip file. See “Installation” on page 86.
Application receives an ″access denied″ exception: A message like the
following is received by the application:
java.io.IOException: CCL6651E: 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, inCICS Transaction Gateway: Programming Guide, for more
information.
KeyStore name not recognized: Java interprets the back slash (\) character
as a parameter delimitter. If you used the back slash character as a directory
separator when entering the path name of the KeyStore file during
146 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
Diagnosing common problems
configuration, Java cannot recognize the name. Use either a forward slash (/)
character, or double back slash (\\) characters, as a separator in the path
name on all operating systems. For example:
/mykeys/jsse/keystore.jks
\\mykeys\\jsse\\keystore.jks
Shortage of resources on the CICS server
You may receive intermittent ECI_ERR_RESOURCE_SHORTAGE return codes
from ECI calls you may to CICS servers. If this is the case, you must increase
the RECEIVECOUNT value on the SESSIONS resource definition on the CICS
server to a value substantially greater than is theoretically necessary, that is,
100. For more information, see “CICS server sessions definition” on page 40.
ECI_ERR_SECURITY_ERROR return code
Possible causes for this return code from an ECI call include:
v Surrogate checking has been enabled in the EXCI options table
DFHXCOPT.
The SURROGCHK option in the DFHXCOPT table enables surrogate
checking, and this defaults to YES. Refer to the CICS External Interfaces
Guide for more information about using this option.
v RACF program control must be active for the SDFHEXCI data set.
To activate program control:
SETROPTS CLASSACT(PROGRAM)
RDEFINE PROGRAM * UACC(READ)
SETROPTS WHEN(PROGRAM)
To add the CICS library when program control is active:
RALTER PROGRAM * ADDMEM*’hlq.SDFHEXCI’/volser/NOPADCHK)
SETROPTS WHEN(PROGRAM) REFRESH
v Extended attributes settings are not specified for certain HFS files.
The following extattr commands mark the load modules used by the CICS
Transaction Gateway as program controlled. Issue commands like the
following from an OMVS shell or a Telnet session:
extattr +p /bin/lib*.so
extattr +p /bin/SECURES
You must specify that the ctgstart script does not share its address space
with any other processes. This is to ensure that the calling address space
(JVM) is not “contaminated” by a non-program-controlled load module. To
force the JVM to use its own non-sharable address space, enter:
extattr -s /bin/ctgstart
The JVM must also be program controlled. (By default, JVM 1.3 or later is
installed as program controlled.) If necessary issue the command
extattr +p javapath/bin/*
Chapter 9. Problem determination 147

|
|
Diagnosing common problems
where javapath is the location of the JVM. For further information, see
“Configuring CICS Transaction Gateway for use with RACF ® ” on page 65.
v The ctgstart script does not have the ’Share Address Space’ extended
attribute bit turned off with extattr -s. If this is not the case, the error occurs
on ECI_SYNC or ECI_STATE-SYNC calls due to a ’dirty’ address space. See
also “Dirty address space problems”.
v A RACF facility class is not defined.
If you are using userids and passwords that are to be verified by CICS
Transaction Gateway itself, and not passed to CICS for verification, then
you must define a RACF facility class. The name of the facility class must
match the netname parameter on the CONNECTION definition for the
EXCI link, and the value of the DFHJVPIPE environment variable used by
the CICS Transaction Gateway. For more information, refer to “CICS server
connection definition” on page 37.
v The JAVA_PROPAGATE environment variable has not been set for a CICS
Transaction Gateway application running in local:// mode. You must set:
JAVA_PROPAGATE=NO
in the environment that the java application runs under.
If the environment variable is not set, z/OS traces show that a
pthread_security_np call with the CREATE_SECURITY_ENV parameter has
failed with a 157 (EMVSERR) return code.
ECI_ERR_SYSTEM_ERROR return code
This return code can be generated as a result of problems in the CICS address
space. For example, PGMIDERR, a security violation, or program-autoinstall
veto.
It can also be generated in the EXCI code if the userid of the CICS Transaction
Gateway host address space is not PERMITted to the DFHAPPL.dfhjvpipe or
the DFHAPPL.applid facilities.
Dirty address space problems
This problem can result in different ways depending on how the CICS
Transaction Gateway loses its privileged status:
v The ctgstart script still has the ’s’ bit set.
v The SDFHEXCI load library, and any load library defined in the
EXCI_OPTIONS environment variable are not program-controlled.
v The CICS Transaction Gateway HFS is mounted with NOSETUID. The CICS
Transaction Gateway HFS must be mounted with the default of SETUID.
148 CICS Transaction Gateway: z/OS Administration

Program support
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/ts/cics/
and follow the Support link.
Program Support
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
Chapter 9. Problem determination 149

Program Support
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 153. If the RETAIN search is unsuccessful, the
problem is passed on to a Level-2 representative 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 152. 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 153.
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.
150 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Program Support
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.
v A 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 5.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.
Chapter 9. Problem determination 151

Program Support
– Severity level 4 indicates that you are able to use the program with the
problem causing negligible hindrance.
When deciding the severity of the problem, take care to categorize it
correctly, as the procedures followed by the support organization depend
on the severity level supplied.
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.
v If you upload files to a mainframe system, do so in binary rather than
ASCII format.
APARs and fixes
Once 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 in time, 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
152 CICS Transaction Gateway: z/OS Administration

Program Support
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/details.
Chapter 9. Problem determination 153

154 CICS Transaction Gateway: z/OS Administration

Appendix A. Hardware and software
This chapter lists hardware requirements and supported software for all
operating systems on which the CICS Transaction Gateway runs.
Hardware requirements
This section discusses the disk space requirements on z/OS, and general
hardware requirements on distributed platforms.
Disk space requirements on z/OS
CICS Transaction Gateway is normally installed into a directory such as
/usr/lpp/ctg, in USS (see also “Installation path” on page x). In this case,
during installation, the uncompressed tar file is present in the /usr/lpp
directory. The HFS data set for this directory must be large enough to take the
25MB (40 cylinders) that this file occupies. You can delete the files once
installation is complete. Installation also requires 25MB (40 cylinders) in the
/tmp directory.
Once installed, CICS Transaction Gateway occupies 27MB. You need enough
disk space for CICS Transaction Gateway and any logging and tracing files.
IBM recommends that you use a separate HFS data set with a primary
allocation of 40 cylinders for CICS Transaction Gateway software. Increase this
to 50 cylinders if the logging and trace files will be stored in the same HFS
data set. Increase it further if many instances of CICS Transaction Gateway
will run, or if much logging is required. Alternatively, you can use a separate
HFS data set, with a primary allocation of 5 cylinders, for each instance of
CICS Transaction Gateway.
If you use the existing /usr/lpp HFS data set, ensure it has enough space to
take the CICS Transaction Gateway software.
Table 10. Hardware requirements on UNIX systems
AIX LINUX SOLARIS HP-UX
Processor v IBM RISC
System/6000 ®®
v IBM RS/6000 ®®
Scalable
POWERParallel
System (SP2 ® G5, G6, MP3000 or
above
SPARC PA-RISC 1.1 or 2.0
).
© Copyright IBM Corp. 1996, 2002 155

Table 10. Hardware requirements on UNIX systems (continued)
AIX LINUX SOLARIS HP-UX
Terminals Any type of Any standard Any type of Any standard
terminal or telnet or X based terminal or telnet or X based
X/Terminal that terminal that can X/Terminal that terminal that can
can attach to the access Linux. can attach to the access HP-UX.
processor.
processor.
Memory At least 64 MB At least 64 MB At least 64 MB At least 64 MB
Disk space 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB 30MB,plus30MB
for temporary files for temporary files for temporary files for temporary files
used during used during used during used during
installation. installation. installation. installation.
Table 11. Hardware requirements on Windows systems
Processor Any processor capable of running the appropriate
operating system and other prerequisite software.
Network adapters To connect workstations to the LAN, you need a
suitable adapter such as an ethernet adapter.
Memory At least 64 MB.
Disk space You need 30 MB of free disk space for your CICS
Transaction Gateway (including documentation in US
English only).
Supported software
The following products are supported.
You need a further 30 MB for temporary files used
during installation. At least 12 MB of this must be on
your system partition.
Operating systems
CICS Transaction Gateway is supported on the following operating systems:
v AIX V4.3.3 with Service Pack 25
v AIX 5.1
v HP-UX 11.0
v HP-UX 11i (32 bit and as a 32 bit application in 64 bit mode)
v Linux for S/390 ® - SuSE 7.0 (Kernel level 2.2.16)
v Linux for S/390 - SuSE 7.0 (Kernel level 2.4)
v Solaris 7 (32 bit mode and as a 32 bit application in 64 bit mode)
v Solaris 8 (32 bit mode and as a 32 bit application in 64 bit mode)
156 CICS Transaction Gateway: z/OS Administration

v Turbolinux Server 6 for zSeries and S/390 (kernel level 2.2.16)
v Turbolinux Server 6.5 for zSeries and S/390 (kernel level 2.2.19)
v OS/390 V2.10
v z/OS V1.2
v Windows XP Professional
v Windows 2000 Professional with a minimum of Service Pack 1
v Windows 2000 Server (with Windows 2000 Terminal Services feature) with a
minimum of Service Pack 1
v Windows NT Workstation V4.0 with a minimum of Service Pack 6a
v Windows NT Server V4.0 with a minimum of Service Pack 6a.
Notes:
– Windows NT 4 Terminal Server is not supported
– The setting of multiple user interface languages, under Windows
2000 MultiLanguage Version, is not supported.
– If you plan to run CICS Transaction Gateway under load, and
using remote protocols, it is strongly recommended that you use
a server version, rather than a workstation version, of Windows.
Web browsers
v HTML/HTTP functions: Any browser that supports HTML V1.0 should
work with the product.
v Java Functions: Any JDK 1.1 compliant Web browser should work with the
product.
The CICS Transaction Gateway is supported with the following browsers:
v Microsoft Internet Explorer 5.0, 5.5 and 6.0
v Netscape Communicator 4.7 and 6.2
v HotJava Browser V 1.1 (for Solaris)
Note: Applets running within the JVM supplied with the Netscape
Communicator browser fail to make successful connections with the
CICS Transaction Gateway. Message number CCL6652E is returned to
the applet. Currently there is no solution to this problem.
Java applets are supported for compatibility with previous versions of
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.
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
Appendix A. Hardware and software 157

|
|
|
|
|
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 going in
as. Currently there is no solution to this problem.
JDK levels
CICS Transaction Gateway supports JDK levels 1.3 and 1.3.1 at the following
minimum service levels:
v AIX: IBM Java SDK 1.3 (service release 6)
v HP-UX: Java SDK 1.3.0.02
v Solaris: Sun Java SDK SE 1.3.0_04.
v z/OS: IBM Java SDK 1.3
If using the IBM Persistent Reusable JVM, you are recommended to run at a
minimum of 1.3.1S, refresh 10. Do not attempt to use the resettable
functionality of this JVM.
If using Java under DBCS code pages, especially IBM-939, install service
refresh 14 or later.
v Windows: IBM Java SDK 1.3 (service release 6)
JSSE
CICS Transaction Gateway supports JSSE in the the following environments:
v Standard Java runtime environment (JRE).
Only the IBM JSSE is supported:
– AIX: Install the JSSE package supplied with CICS Transaction Gateway
– HP-UX: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
– Linux for S/390: Install the JSSE package supplied with CICS Transaction
Gateway
– Solaris: Install the JSSE package and JCE supplied with CICS Transaction
Gateway
– z/OS with JRE 1.3.1: includes a version of JSSE that CICS Transaction
Gateway supports
– Windows: Install the JSSE package supplied with CICS Transaction
Gateway
v WebSphere Application Server:
All supported levels have built in JSSE support.
CICS Transaction Gateway does not support the use of JSSE with applets.
CICS Servers
A CICS server runs real-time multi-user applications and manages the
associated resources and data. CICS Transaction Gateway is supported with
the following servers:
158 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
v CICS Transaction Server for z/OS V2.2
v CICS Transaction Server for z/OS V2.1 (with APAR PQ30168, for signon
capable terminals, applied)
v CICS Transaction Server for z/OS V1.3 with APAR PQ30168, for signon
capable terminals, applied. Apply z/OS APAR PQ38644, for EXCI, if you
are using the CICS Transaction Gateway for z/OS.
v CICS for MVS/ESA V4.1, with communication through SNA. (with APAR
PQ30167, for signon capable terminals, applied). Apply APAR PN68409 for
EPI emulation. APAR PN79262 is needed for DBCS support.
v CICS for OS/400 ® V4.4
v CICS Transaction Server for OS/2 ® V4.1 with CSD 3
v CICS Transaction Server for VSE/ESA 1.1.0 (with APAR PQ30170, for
signon capable terminals, applied), or a minimum service level of 1.1.1
v TXSeries V4.2 with a minimum of PTF 9 (HP-UX)
v TXSeries V4.3 with a minimum of PTF 4 (Windows NT, AIX, Solaris)
v TXSeries V5.0 (Windows, AIX)
Web servers
Any web server that is supported by your application server should work
with the product.
Application servers
The CICS Transaction Gateway is supported with the following:
v IBM WebSphere Application Server V4.0.1 Enterprise Edition on Windows,
AIX and Solaris.
v IBM WebSphere Application Server V4.0.3 Advanced Edition on Linux/390.
v IBM WebSphere Application Server V4.0.1 for z/OS and OS/390 with PTF
UQ99329 (Service Level W401030).
SNA communications
Customers wishing to use SNA communications should install one of the
following products:
Windows operating systems
Any one of:
v IBM eNetwork Communications Server V6.1, with a minimum of
service level 1
v IBM eNetwork Personal Communications V5.0, with a minimum of
service level 2
v IBM eNetwork Personal Communications V5.5
v Microsoft SNA Server V4.0 with a minimum of SP4
Appendix A. Hardware and software 159

|
|
AIX
IBM eNetwork Communications Server V6.1, with a minimum of service
level 1 (AIX).
SNA is not supported on other UNIX operating systems.
TCP/IP communications
TCP/IP support is provided by the operating system.
TCP62 communications
TCP62 support is provided by CICS Transaction Gateway.
Compilers and application development tools
CICS Transaction Gateway is supported with the following compilers and
application development tools:
AIX
v IBM C for AIX V4.4
v IBM C/Set++ for AIX V3.6, with a minimum of service level 6
v IBM VisualAge ® C++ Professional V4.0
v IBM VisualAge C++ Professional V5.0 (requires AIX version 4.2 or later)
HP-UX
v HP ANSI C B.11.01, with a minimum of service level 7
v HP aC++ B.11.01, with a minimum of service level 6
Linux for S/390
v GNU compiler C runtime V2.95, with a minimum of service level 2
v GNU compiler C++ runtime V2.95, with a minimum of service level 2
Solaris
Sun WorkShop C++ V5.0
Note: The C++ compiler must have all available service patches applied.
Windows
v IBM VisualAge COBOL V3.0
v Microsoft Visual C++ V6.0
v Microsoft Visual Basic V6.0
v Microsoft Visual Basic Script (VBScript) V5.0
Note: The CICS Transaction Gateway does not support use of the COM
libraries with Microsoft Transaction Server (MTS), or the MTS
component of COM+.
Screen readers
The CICS Transaction Gateway is supported with JAWS.
160 CICS Transaction Gateway: z/OS Administration

|
|
|
Other tools
These tools are available for viewing the PDF online documents:
v Adobe Acrobat Reader V5.0
v GhostView V4.0 on Linux
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.
Appendix A. Hardware and software 161

162 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
Appendix B. Supported code pages
The following code pages are supported:
US English
v IBM-1047
Simplified Chinese
v IBM-935
v IBM-1388
Japanese
v IBM-930
v IBM-939
v IBM-1930
v IBM-1939
© Copyright IBM Corp. 1996, 2002 163

164 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The product library and related literature
This chapter lists books on the CICS Transaction Gateway, and related topics.
It also discusses how you can view the online library supplied with the
product.
It consists of the following topics:
“CICS Transaction Gateway books” Read this for a list of all books provided
with the CICS Transaction Gateway.
“Sample configuration documents” on
page 166
Read this for information about a series of
PDF documents that provide step-by-step
guidance on configuring the CICS
Transaction Gateway.
“Redbooks” on page 167 Read this for details of other publications
that contain examples of client/server
configurations.
“Other Useful Books” on page 167 Read this for details of other relevant
publications.
“Obtaining books from IBM” on page 168 Read this for information on downloading
books and ordering hardcopy versions.
CICS Transaction Gateway books
v CICS Transaction Gateway: Windows Administration, SC34-6190
This book describes the administration of the CICS Transaction Gateway for
Windows.
v CICS Transaction Gateway: UNIX Administration, SC34-6139
This book describes the administration of the CICS Transaction Gateway for
UNIX operating systems.
v CICS Transaction Gateway: z/OS Administration, SC34-6191
This book describes the administration of the CICS Transaction Gateway for
z/OS.
v CICS Transaction Gateway: Gateway Messages
This online book lists and explains the error messages that can be generated
by CICS Transaction Gateway.
You cannot order this book.
v CICS Transaction Gateway: Programming Reference, SC34-6140
© Copyright IBM Corp. 1996, 2002 165

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The CICS Transaction Gateway
This book provides information on the APIs of the programming languages
supported by the CICS Transaction Gateway.
There are also additional HTML pages that contain JAVA programming
reference information.
v CICS Transaction Gateway: Programming Guide, SC34-6141
This introduction to programming for the CICS Transaction Gateway
provides the information that you need to allow non-CICS applications to
use CICS facilities in a client/server environment.
Sample configuration documents
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. .
The following scenarios are currently covered:
v Configuring CICS Transaction Gateway for Windows for Microsoft SNA
Server
v Configuring CICS Transaction Gateway for Windows for eNetwork Personal
Communications
v Configuring CICS Transaction Gateway for Windows for TCP62
v Configuring CICS Transaction Gateway for AIX for IBM eNetwork
Communications Server
v Configuring CICS Transaction Gateway for Windows for Communications
Server
v Configuring CICS Transaction Gateway for Terminal Servlets using
WebSphere Application Server for Windows
v Client security configuration
v Configuring CICS Transaction Gateway for WebSphere 4.01 using J2EE
v Configuring CICS Transaction Gateway 4.02 for WebSphere Application
Server on z/OS using J2EE
As more sample configuration documents become available, you can
download them from our Web site at:
www.ibm.com/software/ts/cics/
and follow the Download link.
166 CICS Transaction Gateway: z/OS Administration

Redbooks
Other Useful Books
The following International Technical Support Organization (ITSO) Redbook
publication contains many examples of client/server configurations:
v CICS Transaction Gateway V3.1 The WebSphere Connector for CICS, SG24-6133
This book supersedes the following book:
v Revealed! CICS Transaction Gateway with more CICS Clients Unmasked,
SG24-5277.
v Java Connectors for CICS: Featuring the J2EE Connector Architecture, SG24-6401.
This book provides information on developing J2EE applications.
See also:
v Securing Web Access to CICS, SG24–5756.
v Workload Management for Web Access to CICS, SG24–6118.
You can obtain ITSO Redbooks from a number of sources. For the latest
information, see:
www.ibm.com/redbooks/
CICS Transaction Server publications
Other publications
CICS interproduct communication
The following books describe the intercommunication facilities of the CICS
server products:
CICS Family: Interproduct Communication, SC34-6030
Transaction Server for Windows NT: Intercommunication, SC33-1882
CICS Transaction Server for z/OS: Intercommunication Guide, SC34-6005
CICS Transaction Server for VSE/ESA: Intercommunication Guide, SC33-1665
CICS for OS/400: Intercommunication, SC33-1388
TXSeries: CICS Intercommunication Guide, SC09-3900
CICS for OS/2: Intercommunication, SC33-1583
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:
Transaction Server for Windows NT: Problem Determination, GC33-1883
CICS Transaction Server for z/OS ® Problem Determination Guide, SC34-6002
The product library and related literature 167

Other publications
CICS Transaction Server for VSE/ESA Problem Determination Guide,
GC33-1663
CICS for OS/400 ® : Problem Determination, SC33-1384
TXSeries: CICS Problem Determination Guide, SC33-1565.
You can find information on CICS products at the following Web site:
www.ibm.com/software/ts/cics/
APPC-related publications
The following books are concerned with products providing APPC support:
IBM products
IBM Communications Server for AIX for AIX:
IBM Communications Server for AIX: Quick Beginnings, GC31-8583
IBM Communications Server for AIX: General Information, GC31-8584
IBM Communications Server for AIX: Administration, SC31-8586
IBM Communications Server for AIX: Administration Command Reference,
SC31-8587
Systems Network Architecture (SNA)
SNA Formats, GA27-3136
Systems Network Architecture Technical Overview, GC30-3073
TCP62–related publications
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
GC31–7073
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074
Obtaining books from IBM
For information on books you can download, visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link.
You can order hardcopy books:
v Through your IBM representative or the IBM branch office serving your
locality.
v By calling 1-800-879-2755 in the United States.
v From the Web site at:
www.ibm.com/shop/publications/order
168 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Accessibility
The English version of the CICS Transaction Gateway has been tested for
accessibility on the Windows operating system. The product is accessible.
Documentation
Download the CICS Information Center for an html version of the
documentation. Go to this Web page
www.ibm.com/software/ts/cics/
iKeyMan
Samples
and follow the Library link.
See this Web site for information:
www.tivoli.com
The samples are not accessible.
Configuration tool accessibility
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+letter
Certain actions have shortcuts assigned to them. Hold down the Ctrl key
and type the letter to do the action.
Ctrl+letter Action
C Copies the selected value.
N Creates a new configuration.
© Copyright IBM Corp. 1996, 2002 169

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Ctrl+letter Action
O Opens an existing configuration.
P Pastes.
S Saves the current configuration.
U Cuts the selected value.
V Pastes.
W Creates a new server definition.
X Cuts the selected value.
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 tree 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 tree is active.) Move up and down through the tree.
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.
Control+Page Up
Scroll left.
Control+Page Down
Scroll right.
Control+Tab
Use this (rather than Tab) on panels that contain a table to cycle between
the tree, objects on the panel, and the buttons. Use Control+Shift+Tab to
move backwards.
Enter
Activates a button in the Task Guide.
Escape
Closes the menu.
F2 Select and change an editable number field in a table, for example the
Bias value field on the Program definition for managing workload panel.
170 CICS Transaction Gateway: z/OS Administration

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
F6 (Applies if the tree or the panel is active.) Toggles between the tree and
the panel.
F8 (Applies if the tree or the panel is active.) Allows you to gain control of
the split between the tree and 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
tree, increase the width of the panel).
v Press the right arrow key to move the split right (increase the width of
the tree, decrease the width of the 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.
Shift+Tab
If the cursor is on a field in the panel other than the first field, moves
backwards through the fields. Otherwise, toggles between the tree and the
panel.
Space
1. Activates a button.
2. Selects a checkbox.
3. Selects a node in the tree.
Tab
Cycles through the tree, fields in the panel, and the buttons.
Customizing colors and fonts
Use the Settings option on the menu to change colors and fonts. Settings are
not applied consistently on the Task Guide.
To make them more noticeable, the names of items that contain errors are
displayed in the original typeface, in red and underlined.
Using help
Screen readers read the entire page in the help window, rather than the area
required by a user who has pressed F1. Also, the help window is not
navigable by the keyboard. The solution is to open the help files, which are
html files, in a browser outside the configuration tool. The help file index is
cclhlp15.htm in directory: where represents the directory
Accessibility 171

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
containing the help files in these languages:
Language
English html
German html_de
Spanish html_es
French html_fr
Italian html_it
Japanese html_ja
Korean html_ko
Turkish html_tr
Simplified Chinese html_zh
Task Guide
Screenreaders cannot read the Task Guide; do not use the Task Guide if you
use a screenreader. Use the menu in the configuration tool to add servers
(Tools —> New server). Use the tree structure to enable protocols that the
Java gateway will use.
172 CICS Transaction Gateway: z/OS 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.
A
abend. The termination of a task, job, or
subsystem because of an error condition that
recovery facilities cannot resolve.
APAR. (Authorized program analysis report.) A
report on the basis of which IBM supplies a fix
of a temporary corrective nature to elements of
function SYSMODs. APAR fixes are called
″corrective″ service because they are installed to
cure problems currently being experienced by an
installation. The APAR fix is usually in the form
of either a modification to a load module or an
update to card-image data. It is intended as a
temporary arrangement until a preventive service
(PTF) is issued to fix the problem permanently.
This PTF supersedes the APAR fix, and indeed
specifies this relationship on its ++VER
statement.
API. Application programming interface.
APING. A command used to verify an APPC
link.
APPC. Advanced program-to-program
communication. 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.
applet. A Java program that is downloaded to,
and executed on, a Web browser or network
computer. See also servlet.
applid. In CICS, a system initialization and
terminal control parameter that identifies the
CICS system to other remote systems.
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 facility that enables terminal
definitions to be created automatically in a CICS
server on request. The definition is deleted when
the client terminal is logged off.
automatic transaction initiation (ATI). The
process whereby a transaction request made
internally within a CICS system or network leads
to the scheduling of the transaction. An ATI
request from a CICS Transaction Gateway can
cause the initiation of a transaction in a CICS
server system.
B
beans. See JavaBeans .
BIND. 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.
C
CA. See certification authority.
CEDA. A CICS transaction that defines
resources online.
© Copyright IBM Corp. 1996, 2002 173

Glossary
certification authority. In computer security, an
organization that issues certificates. The
certification 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 External Call Interface (EXCI). An
application programming interface that enables a
program running on Z/OS, such as CICS
Transaction Gateway, to call a program running
in a CICS region. The programs can transfer data
between each other using a communication area.
Compare with External Call Interface (ECI).
CICS Gateway for Java. In CICS Universal
Clients Version 2, an interface between a Java
program and CICS that allows a Java-enabled
browser to dynamically download a Java Applet
and transparently access CICS data. This has
been replaced by the CICS Transaction Gateway.
CICS on open systems. A term used to refer
generically to the products: CICS for HP-UX,
CICS for Sun Solaris, TXSeries for AIX, TXSeries
for HP-UX, and TXSeries for Solaris.
CICS on System/390. A term used to refer
generically to the products CICS Transaction
Server for z/OS , CICS for MVS/ESA, CICS
Transaction Server for z/OS, CICS Transaction
Server for VSE/ESA, and CICS/VSE ® .
cicscli. A command that starts and stops the
Client daemon, checks the availability of servers,
and sets other options.
cicsprnt. A command that allows you to define
a printer terminal on the Client daemon
workstation. The command enables CICS
applications running on the server to direct
output to the client-attached printer.
cicsterm. A command that provides 3270
emulation and enables connection to a CICS
region.
174 CICS Transaction Gateway: z/OS Administration
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. An environment variable that tells
the JVM and other Java applications where to
find the class libraries, including user-defined
class libraries.
Client API. On distributed platforms running
non-Java applications, the interface between the
Client application and the Client daemon.
client application. A user application, written in
a supported programming language other than
Java, that communicates directly with the Client
daemon.
Client daemon. The Client daemon (process
cclclnt) exists only on distributed platforms. 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. A distributed application design
model, in which the client sends a request to its
partner, the server, which executes the request
and returns the results to the client. This design
model is associated typically with cooperative
processing.
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. File CICSCOL.INI used by
the CICS Transaction Gateway to customize the
3270 screen color attributes on client
workstations.
COMMAREA. A communication area that is
used for passing data both between programs
within a transaction and between transactions.

Common Object Request Broker Architecture
(CORBA). An industry standard for an interface
definition language that enables different object
request brokers to interoperate.
configuration file. The file CTG.INI containing
information telling CICS Transaction Gateway
about the CICS servers that it can connect to, and
the communication protocols to use.
configuration tool. A graphical user interface
that allows you to configure the CICS
Transaction Gateway.
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.
control table. In CICS, a storage area used to
describe or define the configuration or operation
of the system.
conversation. The communication between a
CICS Transaction Gateway and a CICS server. In
APPC, a connection between two transaction
programs over an LU-LU session that allows
them to communicate with each other while
processing a transaction. See also session.
conversation security. In APPC, a process that
allows validation of a user ID or group ID and
password before establishing a connection.
cooperative processing. A subset of distributed
processing, in which at least the user interface
(presentation) aspect of the application runs on a
programmable workstation.
CORBA. See Common Object Request Broker
Architecture.
ctgstart. A command that starts the gateway
daemon.
D
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.
Glossary
dependent LU. A logical unit (LU) that can
receive, but not send a BIND, and which
supports only single sessions. See BIND.
digital certificate. A form of personal
identification that can be verified electronically.
Only the certificate owner who holds the
corresponding private key can present a
certificate for authentication through a Web
browser session. Anyone can verify that the
certificate is valid by using a readily available
public key.
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. A link that enables
an application program running on one CICS
system to link to another application program
running in another CICS system.
Glossary 175

Glossary
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.
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.
E
EBCDIC. Extended binary-coded decimal
interchange code. A coded character set of 256
8-bit characters developed for the representation
of textual data.
ECI. See external call interface.
emulator, 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. In the CICS Transaction
Gateway the terminal emulation function allows
client workstations to run CICS transactions that
use 3270 data flows.
176 CICS Transaction Gateway: z/OS Administration
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.
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 10–megabit or 100–megabit
baseband 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 CICS External Call Interface.
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.
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.
F
firewall. A configuration of software that
prevents unauthorized traffic between a trusted
network and an untrusted network.

G
gateway. A device that connects two dissimilar
LANs, or that connects a LAN to a wide area
network (WAN), midrange computer, or
mainframe computer. A gateway device has its
own processor and memory and may perform
protocol conversion. A gateway handles multiple
communication sessions simultaneously.
gateway classes. The interface for Java Client
applications to connect to the Gateway daemon.
The Gateway classes, which are supplied with
the CICS Transaction Gateway, must be in the
classpath for Java Client applications to run.
gateway daemon. Used only in remote mode,
the Gateway daemon listens on protocols defined
in CTG.INI for gateway requests from remote
Java client applications. It issues these requests to
the Client daemon on distributed platforms, and
directly to CICS over the EXCI on z/OS. The
Gateway daemon runs the protocol listener
threads, the worker threads and the connection
manager threads. It uses the GATEWAY section
of CTG.INI (and on z/OS the ctgenvvar script)
for its configuration.
H
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 in an internet.
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
domain name of a host.
HTTP. In the Internet suite of protocols, the
protocol that is used to transfer and display
hypertext and XML documents.
HTTPS. A TCP/IP protocol that World Wide
Web servers and Web browsers use to transfer
and display documents secured by SSL.
I
iKeyman. A tool supplied with the Gateway for
maintaining digital certificates for SSLight and
JSSE.
independent LU. A logical unit (LU) that can
both send and receive a BIND, and which
supports single, parallel, and multiple sessions.
See BIND.
internet. A collection of networks
interconnected by a set of routers that allow
them to function as a single, large network.
Contrast with Internet.
Internet. The internet administered by the
Internet Architecture Board (IAB), consisting of
large national backbone networks and many
regional and campus networks all over the
world. The Internet uses the Internet suite of
protocols.
Internet address. See IP address.
Glossary
Internet Architecture Board. The technical body
that oversees the development of the internet
suite of protocols known as TCP/IP.
Internet Packet Exchange (IPX). In Novell
NetWare LANs, a communication protocol that
sends data packets to requested destinations.
Internet Protocol (IP). In TCP/IP, a protocol
that routes data from its source to its destination
in an Internet environment.
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.
intranet. A private network that integrates
Internet standards and applications (such as Web
browsers) with an organization’s existing
Glossary 177

Glossary
computer networking infrastructure. Compare
with Internet and internet.
IP. Internet Protocol.
IPX. Internet Packet Exchange.
J
J2EE. (Java 2 Platform, Enterprise Edition.) 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.
Java. An object-oriented programming language
for portable interpretive code that supports
interaction among remote objects.
JavaBeans. A platform-independent, software
component technology for building reusable Java
components called beans. Once built, these beans
can be made available for use by other software
engineers or they can be used in Java
applications. Also, using JavaBeans, software
engineers can manipulate and assemble beans in
a graphical drag-and-drop development
environment.
Java client application. A Java application,
servlet or applet that communicates with the
Gateway classes.
Java development kit (JDK). A software
package that can be used to write, compile,
debug, and run Java applets and applications.
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 Secure Socket Extension (JSSE). An
implementation of SSL, written in Java, and
supported by CICS Transaction Gateway.
178 CICS Transaction Gateway: z/OS Administration
Java Virtual Machine (JVM). A software
implementation of a processor that runs
compiled Java code (applets and applications).
JDK. See Java development kit (JDK).
JNI. See Java Native Interface (JNI).
JSSE. See Java Secure Socket Extension (JSSE).
JVM. See Java Virtual Machine (JVM).
K
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.
KeyRing or KeyStore. In computer security, a
file that contains public keys, private keys,
trusted roots, and certificates.
L
LAN. See local area network.
local area network (LAN). A network of
workstations, or terminals, or both, where all the
connected systems are relatively near to each
other. See wide area network.
local mode. Describes a Java Client application
using the Gateway local protocol. The Gateway
daemon is not used in local mode; on distributed
platforms, the Gateway classes interface directly
with the Client daemon API, and with the EXCI
on z/OS. See remote mode.
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.

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.
LU-LU session type 6.2. In SNA, a type of
session for communication between peer
systems. Synonymous with APPC protocol.
LU 6.2. See APPC.
M
MAC. Medium access control.
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.
N
name server. In TCP/IP, synonym for Domain
Name Server In Internet communications, the
host that translates host names into their
respective internet addresses when requested by
the hosts on the network A physical device, and
its associated software, that enables a processor
or controller to be connected to a network.
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.
O
object. In object-oriented programming, a
concrete realization of a class that consists of
data and the operations associated with that
data.
object request broker (ORB). Software that
serves as an intermediary by transparently
enabling objects to exchange requests and
responses.
OO. Object-oriented.
P
Glossary
pacing. A technique by which a receiving
station controls the rate of transmission of a
sending station to prevent overrun.
packet internet groper (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.
Glossary 179

Glossary
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. Packet internet groper. The command
that sends an ICMP Echo Request packet to a
gateway, router, or host with the expectation of
receiving 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. Primary logical unit. 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.
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 (LU) that contains the primary half-session
for a particular LU-LU session. Contrast with
secondary logical unit. See also logical unit.
Note: A particular logical unit may contain
primary and secondary half-sessions for
different active LU-LU sessions.
protocol boundary. The signals and rules
governing interactions between two components
within a node.
R
RACF. Resource Access Control Facility. An IBM
licensed program that provides access control by
identifying users to the system; verifying users of
the system; authorizing access to protected
180 CICS Transaction Gateway: z/OS Administration
resources; logging detected, unauthorized
attempts to enter the system; and logging
detected accesses to protected resources.
region. A physical instance of a CICS server.
remote mode. Describes a Java Client
application using a Gateway network protocol to
connect to the Gateway daemon. See local mode.
remote procedure call (RPC). Remote procedure
calls are analogous to the standard procedure
calls used in modern programming, providing
modularity and reducing code size. The main
difference between standard procedure calls and
remote procedure calls is that in a remote
procedure call, the called procedure is being
executed by a different process than the caller. To
the calling procedure, a remote procedure call
looks the same as a call to a local procedure.
When a program makes a remote procedure call
to a remote application, the procedure’s
parameters are automatically bundled into a
request message, which is then sent to the
remote program or system.
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.
RU. Request unit. Response unit.
RPC. See remote procedure call.
S
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.
servlet. A Java servlets program that run on a
Web server machine, unlike Java applets, which
are downloaded to a Web browser. Java servlets
have become popular as a replacement for CGI
(Common Gateway Interface) programs.
session. In SNA, a logical connection between
two network addressable units (NAUs) that can
be activated, tailored to provide various
protocols, and deactivated as requested. The
session activation request and response can
determine options for such things as rate and
concurrency of data exchange, control of
contention and error recovery, and characteristics
of the data stream. Sessions compete for network
resources, such as links within the path control
network. For routing purposes, each session is
identified by the network or local addresses of
the session partners. See LU-LU session, LU-LU
session type.
session limit. In SNA, the maximum number of
concurrently active LU-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.
signon capable terminal. A signon capable
terminal allows signon transactions, either
CICS-supplied (CESN) or user-written, to be run.
Contrast with signon incapable terminal.
SIT (system initialization table). A table
containing parameters used to start a CICS
control region.
SNA gateway. A gateway that handles multiple
APPC communication sessions simultaneously.
See gateway.
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.
SSL. See Secure Sockets Layer (SSL).
Glossary
SSLight. An implementation of SSL, written in
Java, and supported by CICS Transaction
Gateway.
System Management Interface Tool (SMIT). In
the AIX operating system, a set of menu-driven
services that facilitate the performance of system
tasks such as installation, management,
configuration, and diagnosis.
standard error. In many workstation-based
operating systems, the output stream to which
error messages or diagnostic messages are sent.
subnet. In TCP/IP, a part of a network that is
identified by a portion of the Internet address.
Synonym for subnetwork.
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.
Systems Network Architecture (SNA). The
description of the logical structure, formats,
protocols, and operational sequences for
transmitting information units through, and
controlling the configuration and operation of,
networks.
System SSL. An implementation of SSL,
supported by CICS Transaction Gateway on
z/OS. Written in native code, it supports
Glossary 181

Glossary
hardware encryption technology available to
z/OS, and can be used only for SSL servers on
that operating system.
T
Taskguide. A function of the configuration tool
that provides step-by-step guidance to
configuring your CICS Transaction Gateway. .
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. Transmission Control Protocol/Internet
Protocol.
TCP/IP address. An address that uniquely
identifies a machine on a network. A machine
can have several threads of execution running at
the same time; a TCP/IP port uniquely identifies
a particular thread.
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.
Terminal Servlet. A Java program that allows
you to use a Web browser as an emulator for a
3270 CICS application running on any CICS
server.
thread. A stream of computer instructions that
is in control of a process. A multithread process
begins with one stream of instructions (one
thread) and may later create other instruction
streams to perform tasks.
token ring. A network with a ring topology that
passes tokens from one attaching device to
another; for example, the IBM Token-Ring
network.
trace. A record of data that provides a history of
events that occurred in a system. The process of
recording the sequence in which the statements
182 CICS Transaction Gateway: z/OS Administration
in a program are executed and, optionally, are
the values of the program variables used in the
statements.
transaction program. A program that uses the
APPC application program interface (API) to
communicate with a partner application program
in the same node or at a partner node.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A set of communications protocols
that support peer-to-peer connectivity functions
for both local and wide area networks. TCP/IP
can be used for client/server links between the
Client daemon and, for example, CICS for OS/2,
CICS for Windows NT.
type 2.0 node. An SNA node that attaches to a
subarea network as a peripheral node and
provides full 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.
U
URL. (Uniform Resource Locator.) 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.
user session. Any APPC session other than a
SNASVCMG session.
V
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.

W
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.
Glossary
Glossary 183

Glossary
184 CICS Transaction Gateway: z/OS Administration

Index
Special characters
_BPX_SHAREAS 48, 67, 140
_BPX_SPAWN_SCRIPT 140
x
A
accessibility 169
Acrobat 161
adapters 156
administration 128
Adobe 161
APAR (authorized program analysis report)
authorization 152
closing 153
documentation needed 150
process 152
submitting 152
API (Application Programming Interface) 3
application development tools 160
Application Programming Interface (API) 3
application servers 21, 159
application tracing 135
ARM 119
ASSIZEMAX parameter 123
asymmetric keys 5
AUTH_USERID_PASSWORD environment variable 48
authentication 8
Authorized Hosts configuration setting 62
automatic restart management 119
B
books 165
CICS Transaction Gateway 165
BPX.FILEATTR.APF 120
BPX.FILEATTR.PROGCTL 65, 66
BPX.SERVER 66
BPX.SERVER FACILITY profile 67
BPXBATCH program 123
BPXPRMxx member 29, 31, 73, 123, 144
browsers 20, 157
C
CA (certification authority) 6
CCF 22
certification authority (CA) 6
cfwk.zip 146
CICS Description configuration setting 64
CICS External Call Interface (EXCI) 1, 3
CICS Gateway for Java (MVS) 23
CICS resource adapters 68
CICS Server configuration setting 64
CICS server resource definitions 37
CICS servers 21, 158
CICS Transaction Gateway for z/OS 24
configuring 43
installing 25
migration 23, 24
problem determination 131
software requirements 20
startup options 117, 127
tar file 26
uninstalling 34
CICSCLI environment variable 49, 53
cicseci resource adapter 68
cicseci.rar 67
cicseciRRS.rar 67
CLASSPATH environment variable 49, 107, 143, 146
ClientSecurity 69
code pages 32, 33
code sets 33
Common Client Interface (CCI) 13
Common Connector Framework 22
communication protocols 159
compilers 160
configuration
environment variables 48
configuration file
referencing 49, 53
configuration settings
Authorized Hosts 62
CICS Description 64
CICS Server 64
Connection timeout (ms) 59
CTG User Classpath 65
CTG User Libpath 65
Display TCP/IP hostnames 57
Drop working connections 60
Enable protocol handler 59
Enable reading input from console 57
EXCI Net Name 65
EXCI Options 65
Gateway 63
Gateway trace file 64
Gateway trace wrap size 64
Handler wakeup timeout (ms) 59
High Level Qualifier 65
Idle timeout (ms) 59
Initial number of Connection Manager threads 56
© Copyright IBM Corp. 1996, 2002 185

configuration settings (continued)
Initial number of Worker threads 56
Java clients obtaining generic ECI replies 58
KeyRing database 61
KeyRing or Keystore name 61
KeyRing or Keystore password 61
Library Name 65
Log client connections and disconnections 58
Max dedicated connections 62
Maximum number of Connection Manager
threads 56
Maximum number of Worker threads 57
Ping time frequency (ms) 60
Port 59
Require clients to use security classes 60
RRM Name 65
SO_LINGER setting 60
Timeout for in-progress requests to complete
(ms) 58
Use client authentication 60
Use RACF Authentication 64
Validate Units of Work 58
Worker thread available timeout (ms) 58
configuration tool 52
configuration tool help 171
connection definition 37
Connection timeout (ms) configuration setting 59
ConnectionManager threads 117
ConnectionURL 68
Corrective Service Diskette (CSD) 153
CSD (Corrective Service Diskette) 153
CTG User Classpath configuration setting 65
CTG User Libpath configuration setting 65
CTG_JNI_TRACE 63, 136
CTG_RRMNAME environment variable 49
CTG.INI 43
ctgarm command 120
ctgcfg command 52
ctgclient.jar 143
ctgenvvar script 47
ctgenvvarsamp 43
ctgenvvarsamp script 47
ctgikey 76, 87
ctginstall script 32
ctgjnilog 133
CTGSAMP.INI 43
ctgserver.jar 143
ctgstart command 117, 123
ctgstart script 48, 148
D
DBCS 34
development tools 160
DFHJVPIPE environment variable 39, 49, 148
DFHJVSYSTEM_ environment variables 49
186 CICS Transaction Gateway: z/OS Administration
DFHXCOPT, EXCI options table 50, 52
DFHXCURM 42
diagnosing common problems 139
if a process locks 145
Java exceptions 142
java.lang.OutOfMemory exception 143
SSL exceptions 145
digital certificates 5, 8
externally signed 77, 87, 96
maintaining 76, 87, 95
self-signed 82, 91, 101
digital signatures 5
directory structure 33
disability 169
disk space required 156
DISPLAY environment variable 34
Display TCP/IP hostnames configuration setting 57
distinguished name (DN) 6
DN (distinguished name) 6
documentation 165
documenting problems 150
Drop working connections configuration setting 60
E
ECI (External Call Interface) 1, 3
Enable protocol handler configuration setting 59
Enable reading input from console configuration
setting 57
encryption 5, 8
Enterprise Information Systems (EIS) 13
environment variables
AUTH_USERID_PASSWORD 48
CICSCLI 49, 53
CLASSPATH 49, 107, 146
CTG_JNI_TRACE 63, 136
CTG_RRMNAME 49
DFHJVPIPE 49, 148
DFHJVSYSTEM_ 49
EXCI_LOADLIB 50, 52
EXCI_OPTIONS 50, 52, 148
JAVA_COMPILER 22
JAVA_HOME 76, 87
JAVA_PROPAGATE 22, 148
LD_LIBRARY_PATH 50
LIBPATH 22, 50, 97, 102
RRM_NAME 49
STEPLIB 50, 66, 127
EPI (External Presentation Interface) 1
ESI (External Security Interface) 1
etc/profile 22
EXCI (CICS External Call Interface) 1, 3
EXCI Allocate_Pipe call 141
EXCI Net Name configuration setting 65
EXCI Open_Pipe call 141
EXCI Options configuration setting 65

EXCI options table, DFHXCOPT 50, 52
EXCI pipe limitations 141
EXCI pipes
Resuse 42
EXCI_LOADLIB environment variable 50, 52
EXCI_OPTIONS environment variable 50, 52, 148
extattr command 65, 147
External Call Interface (ECI) 1, 3
External Presentation Interface (EPI) 1
External Security Interface (ESI) 1
externally-signed certificates 7
F
firewalls 12
G
Gateway configuration setting 63
Gateway trace file configuration setting 64
Gateway trace wrap size 64
Gateway tracing 134
Gateway.properties file 52
generic ECI replies
Configuration 58
GhostView 161
glossary of terms and abbreviations 173
gskkyman 95
H
Handler wakeup timeout (ms) configuration
setting 59
hangs 145
help 171
High Level Qualifier configuration setting 65
HTTP (Hypertext Transfer Protocol) 2
HTTP over SSL (HTTPS) 2
HTTPS 10
HTTPS (HTTP over SSL) 2
Hypertext Transfer Protocol (HTTP) 2
I
Idle timeout (ms) configuration setting 59
iKeyMan 76, 87
distributing to client workstations 77
Initial number of Connection Manager threads
configuration setting 56
Initial number of Worker threads configuration
setting 56
install_path x
installation 25
migration 23, 24
path x
installation path x
installation problems 139
J
J2EE
resource adapter files 67
resource adapters 3
Java
applet 11
application 12
classes 3
firewall 12
Java language 11
servlet 11
Java development kit 21, 158
Java exceptions 142
Java Secure Socket Extension (JSSE) 21, 158
JAVA_COMPILER environment variable 22
JAVA_HOME environment variable 76, 87
JAVA_PROPAGATE 67
JAVA_PROPAGATE environment variable 22, 48, 148
java.lang.OutOfMemory exception 143
JDK levels 21, 158
JNI error messages 133
JNI tracing 63, 128, 135
JSSE 7, 9, 21, 86, 87, 158
installation 86
migration from SSLight 86
K
keyboard 169
KeyRing database configuration setting 61
KeyRing or Keystore name configuration setting 61
KeyRing or Keystore password configuration
setting 61
KeyRingClass 70
KeyRingPassword 70
KeyRings 7, 76
KeyStores 7, 87
L
LD_LIBRARY_PATH environment variable 50
LIBPATH environment variable 22, 50, 97, 102
Library Name configuration setting 65
license file 32, 33
local gateway connection 12
locales 32
locks 145
M
Max dedicated connections configuration setting 62
MAXASSIZE parameter 123
MAXCPUTIME value 73
Maximum number of Connection Manager threads
configuration setting 56
Maximum number of Worker threads configuration
setting 57
MAXTHREADS parameter 15, 144
Index 187

MAXTHREADSTASK parameter 15
memory leak 143
messages 132
migrating from CICS Gateway for Java (MVS) 24
Migrating from CICS Transaction Gateway Version
4 24
migration issues 23, 24
N
network gateway connection 12
network name 35
network security
AUTH_USERID_PASSWORD environment
variable 48
authentication 8
certification authority (CA) 6
concepts 4
ctgikey 76, 87
defining a RACF facility class 148
digital certificates 5, 8
externally signed 77, 87, 96
maintaining 76, 87, 95
self-signed 82, 91, 101
digital signatures 5
distinguished name (DN) 6
encryption 5, 8
exits 34
externally-signed certificates 7
gskkyman 95
HTTPS 10, 107
iKeyMan 76, 87
distributing to client workstations 77
JSSE 7, 9, 86, 87
installation 86
migration from SSLight 86
KeyRings 7, 76
keys 5
KeyStores 7, 87
mapping client certificates to RACF userids 105
marking programs as program-controlled 147
migrating old self-signed certificates 86, 95
permissions to security class 67
RACDCERT command 105
security exits 10
self-signed certificates 7
setting extended attributes on HFS files 66, 147
signer certificate 6
SSL 8, 107
SSL handshaking 8
SSLight 9, 76
surrogate options in DFHXCOPT 52, 147
System SSL 9
trusted root key 6
X.509 protocol 6, 8
188 CICS Transaction Gateway: z/OS Administration
O
operating systems 20, 156
P
Password 69
PDF library, extracting 35
performance
assessing 109
CICS Transaction Gateway configuration 110
Java considerations 112
monitoring 114
other system factors 113
tracing 114
Ping time frequency (ms) configuration setting 60
PMR (Problem Management Record) 149
Port configuration setting 59
port numbers 141
PortNumber 69
problem determination
application tracing 135
CICS server resources 147
diagnosing common problems 139
Gateway tracing 134
installation 139
JNI tracing 135
messages 132
port numbers 141
preliminary checks 131
tracing 133
Problem Management Record (PMR) 149
problem reporting
documenting problems 150
information needed 151
support organization 149
problems, diagnosing 139
process locks 145
program control 147
program controlled 65
program support 149
protocols
HTML 14
HTTP 2
HTTPS 2
SSL 2, 8
TCP/IP 2
PTF (Program Temporary Fix) 153
pthread_security_np 65
public key encryption 5
publications, CICS Transaction Gateway 165
R
RACDCERT command 105
RACF
AUTH_USERID_PASSWORD environment
variable 48

RACF (continued)
configuring CICS Transaction Gateway to use
RACF 65
defining a RACF facility class 148
mapping client certificates to RACF userids 105
marking programs as program-controlled 147
problems 147, 148
RACDCERT command 105
setting extended attributes on HFS files 66, 147
userids 105
railroad diagrams x
re-authentication support 70
README file 19
region size considerations 123, 144
Require clients to use security classes configuration
setting 60
resource adapter files 67
resource adapters 68
resource adapters, J2EE 3
RETAIN database 149
RETAIN problem management system
APARs 152
Problem Management Record 149
RRM Name configuration setting 65
RRM_NAME environment variable 49
S
screen readers 160
SDFHEXCI 66
SDFHEXCI data set 147
Secure Sockets Layer (SSL) 2, 8
security exits 10, 34
self-signed certificates 7
ServerName 69
servers
application 21, 159
CICS 21, 158
web 21, 159
ServerSecurity 70
servlets 11
sessions definition 37
shortcut keys 169
signer certificate 6
SNA 159
SO_LINGER setting configuration setting 60
software requirements
CICS Transaction Gateway for z/OS 20
SSL (Secure Sockets Layer) 2, 8
SSL exceptions 145
SSL handshaking 8
SSLight 9, 76
standard error (stderr) file 132, 135
standard output (stdout) file 132
starting CICS Transaction Gateway 117
starting CICS Transaction Gateway with JCL 121
starting multiple CICS Transaction Gateways 124
STDENV data set 126
stderr 132, 135
stdout 132
STEPLIB environment variable 50, 66, 127
stopping CICS Transaction Gateway 127
support organization
program support 149
sending documentation to 152
SURROGCHK, DFHXCOPT table option 52, 147
symmetric keys 5
syntax notation x
SYS1.PARMLIB 73
System SSL 9
T
TCP/IP (Transmission Control Protocol/Internet
Protocol) 2, 160
TCP62 160
TCPAdmin protocol settings 62
TCPIP.PROFILE 139
Telnet 157
thread limits 15
Timeout for in-progress requests to complete (ms)
configuration setting 58
tools
application development 160
other 161
TPNName 69
trace 118, 134
trace options on ctgstart command 118, 134
TraceLevel 70
tracing 71, 133
dynamic 128
Gateway daemon 128
JNI 128
levels 71
performance considerations 135
query current trace settings 128
tracing, JNI 135
TranName 69
transaction support 70
Transmission Control Protocol/Internet Protocol
(TCP/IP) 2
trusted root key 6
U
uninstalling 34
UNIX System Services parameters
MAXTHREADS 15
MAXTHREADSTASK 15
upgrading 23, 24
Use client authentication configuration setting 60
Use RACF Authentication configuration setting 64
Userid 69
Index 189

V
Validate Units of Work 58
W
web browsers 20, 157
web servers 21, 159
Web servers 13
Work load management 42
Worker thread available timeout (ms) configuration
setting 58
Worker threads 117
X
X-Windows 34
X.509 protocol 6, 8
XAResource 70
Z
z/OS Environment settings
CTG User Classpath 65
CTG User Libpath 65
EXCI Net Name 65
EXCI Options 65
High Level Qualifier 65
Library Name 65
RRM Name 65
Use RACF Authentication 64
z/OS Server settings
CICS Description 64
CICS Server 64
z/OS shell environment 22
190 CICS Transaction Gateway: z/OS Administration

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.
© Copyright IBM Corp. 1996, 2002 191

Trademarks
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 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 CICS
IBM MVS
OS/2 z/OS
System/390 TXseries
WebSphere
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States, other countries, or both.
192 CICS Transaction Gateway: z/OS Administration

Java, and all Java-based trademarks and logos are trademarks of Sun
Microsystems, Inc. in the United States, or other countries, or both.
UNIX is a registered trademark in the United States and other countries
licensed exclusively through X/Open Company Limited.
Other company, product or service names may be trademarks or service
marks of others.
Notices 193

194 CICS Transaction Gateway: z/OS 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, 2002 195

����
Program Number: 5724-D12
Printed in U.S.A.
SC34-6191-00

Spine information:
��� CICS Transaction Gateway z/OS Administration Version 5.0

CICS Transaction Gateway
Programming Guide
Version 5.0
���
SC34-6141-00

CICS Transaction Gateway
Programming Guide
Version 5.0
���
SC34-6141-00

Note!
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page 239.
First Edition (July 2002)
This edition applies to Version 5.0 of CICS ® Transaction Gateway, program number 5724-D12. It will also apply to all
subsequent versions, releases, and modifications until otherwise indicated in new editions.
This edition replaces SC34-5946, SC34-5947, SC34-5945, SC34-5938. Vertical lines at the left side of the page indicate
material that is new to this edition.
© Copyright International Business Machines Corporation 2002. 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
Who should read this book . . . . . . . vii
Conventions and terminology used in this
book . . . . . . . . . . . . . . vii
Installation path. . . . . . . . . . ix
Directory delimiters . . . . . . . . ix
Programming language specific. . . . . ix
Operating system specific . . . . . . ix
Summary of changes . . . . . . . . xi
Part 1. Language independent
information . . . . . . . . . . . 1
Chapter 1. Getting started . . . . . . . 3
Overview . . . . . . . . . . . . . 3
External Call Interface (ECI) . . . . . . . 3
External Presentation Interface (EPI) . . . . 4
External Security Interface (ESI) . . . . . . 5
Using the external access interfaces . . . . 6
ECI and EPI exits . . . . . . . . . . 7
Support for object-oriented programming . . 7
Chapter 2. External Call Interface (ECI) . . 9
Overview . . . . . . . . . . . . . 9
ECI function . . . . . . . . . . . 9
Types of ECI call . . . . . . . . . 10
Program link calls . . . . . . . . . . 12
Managing logical units of work . . . . 12
Security in the ECI . . . . . . . . . 15
Status information calls . . . . . . . . 15
How status information is supplied and
used . . . . . . . . . . . . . 15
Reply solicitation calls . . . . . . . . 17
Chapter 3. External Presentation Interface
(EPI) . . . . . . . . . . . . . . 19
Overview . . . . . . . . . . . . . 19
How to use EPI. . . . . . . . . . . 20
Initialization and termination . . . . . 20
Listing the configured servers . . . . . 20
Adding terminal resources . . . . . . 20
Deleting terminal resources . . . . . . 23
Authentication and authorization . . . . 23
Starting transactions . . . . . . . . 24
Events and callbacks . . . . . . . . 24
Processing the events . . . . . . . . 26
Sending and receiving data . . . . . . 27
Managing pseudoconversations . . . . 27
Security in the EPI . . . . . . . . . 27
EPI versions . . . . . . . . . . . . 29
3270 data streams for the EPI . . . . . . 30
Inbound data streams (EPI to CICS) . . . 31
Outbound data streams (CICS to EPI) . . 32
3270 order codes . . . . . . . . . 33
Chapter 4. External Security Interface (ESI) 35
Overview . . . . . . . . . . . . . 35
Benefits of APPC PEM . . . . . . . . 36
Benefits of ESI . . . . . . . . . . . 36
Part 2. Language Specific
information. . . . . . . . . . . 37
Chapter 5. Programming in C and COBOL 39
Supported operating systems . . . . . . 39
Writing the non-CICS applications . . . . 39
Making ECI calls . . . . . . . . . . 40
CICS_ExternalCall . . . . . . . . . 40
Callback routines . . . . . . . . . 41
CICS_EciListSystems . . . . . . . . 41
Making EPI calls . . . . . . . . . . 42
EPI functions. . . . . . . . . . . 42
Callback routines . . . . . . . . . 42
Compiling and linking applications . . . . 42
Client daemon for Windows . . . . . 43
Client daemon for AIX . . . . . . . 43
Client daemon for Solaris . . . . . . 44
Chapter 6. Programming in C++. . . . . 45
Establishing the working environment . . . 45
Windows environment variables . . . . 45
Compiling and Linking . . . . . . . . 47
Multi-Threading . . . . . . . . . . 47
Handling Exceptions . . . . . . . . . 47
Async Exception Handling . . . . . . 48
External call interface . . . . . . . . . 49
Using COMMAREAs . . . . . . . . 49
© Copyright IBM Corp. 2002 iii

|
|
Finding potential servers . . . . . . . 50
Server connection . . . . . . . . . 50
Monitoring server availability . . . . . 51
Passing data to a server program . . . . 52
Controlling server interactions . . . . . 53
Managing logical units of work . . . . 57
Security Management for ECI . . . . . 58
External presentation interface . . . . . . 59
Support for Automatic Transaction
Initiation (ATI) . . . . . . . . . . 61
Starting a 3270 terminal connection to
CICS . . . . . . . . . . . . . 62
Accessing fields on CICS 3270 screens . . 63
EPI call synchronization types . . . . . 64
EPI BMS conversion utility . . . . . . 67
Using EPI BMS Map Classes . . . . . 70
Security Management for EPI . . . . . 71
Chapter 7. Programming in Java . . . . 73
Overview of the programming interface for
Java. . . . . . . . . . . . . . . 73
Writing Java client programs . . . . . . 74
Flow of program control . . . . . . . 75
JavaGateway . . . . . . . . . . . 76
ECIRequest . . . . . . . . . . . 78
Common Connector Framework and
CICSELUW flag. . . . . . . . . . 79
EPIRequest . . . . . . . . . . . 79
Setting up the CLASSPATH . . . . . . 81
Codepage conversion . . . . . . . . 81
Using a browser and CICS Transaction
Gateway on the same workstation . . . 81
Performance issues. . . . . . . . . 81
Tracing in Java client programs . . . . 82
Making ECI calls on z/OS . . . . . . 84
ECI return codes and server errors on
z/OS . . . . . . . . . . . . . 86
Making EPI calls on z/OS . . . . . . 86
EXCI considerations on z/OS . . . . . 86
EPI support classes . . . . . . . . 87
EPI beans . . . . . . . . . . . 101
Security . . . . . . . . . . . . . 111
CICS Transaction Gateway security classes 111
Using a Java 2 Security Manager . . . . 113
Chapter 8. Programming using J2EE . . 115
The Common Client Interface . . . . . . 115
CCI Framework Classes. . . . . . . 115
CCI Input and Output classes . . . . . 116
Connector specification API Javadoc . . 117
iv CICS Transaction Gateway: Programming Guide
J2EE Connector Specification API . . . 117
ECI resource adapter CCI . . . . . . 117
EPI resource adapter CCI . . . . . . 121
Security credentials and the CICS
resource adapters . . . . . . . . . 129
Compiling applications . . . . . . . 129
Compiling and running Enterprise Bean
clients and deploying Enterprise Beans . 129
Using the J2EE CICS resource adapters in a
nonmanaged environment . . . . . . . 130
Creating the appropriate
ConnectionFactory object . . . . . . 130
Storing ConnectionFactory objects . . . 131
Running the J2EE CICS resource adapters
in a nonmanaged environment . . . . 131
J2EE Tracing . . . . . . . . . . . 132
Issues with tracing if ConnectionFactory
serialized . . . . . . . . . . . 132
Resource adapter samples . . . . . . . 133
ECI sample . . . . . . . . . . . 133
EPI sample . . . . . . . . . . . 134
Chapter 9. Programming in COM . . . . 137
Establishing the working environment . . . 137
The COM libraries . . . . . . . . 137
Using the COM classes . . . . . . . . 139
Object Creation and Interfaces . . . . 139
Type Libraries and Visual Basic
Intellisense . . . . . . . . . . . 140
Class summary . . . . . . . . . 141
Exception Handling . . . . . . . . 141
Making an ECI link call to CICS using
Visual Basic. . . . . . . . . . . 144
ECI Userid and Password Management 149
Connection to CICS 3270 applications
using Visual Basic. . . . . . . . . 150
Connecting to CICS 3270 applications
using VBScript . . . . . . . . . . 155
Support for Automatic Transaction
Initiation (ATI) . . . . . . . . . . 155
Security Management . . . . . . . 156
Part 3. Appendixes . . . . . . . 159
Appendix A. ECI extensions that are
environment-dependent . . . . . . . 161
Call type extensions . . . . . . . . . 161

|
Asynchronous program link call, with
notification by message
(ECI_ASYNC_NOTIFY_MSG) . . . . . 161
Asynchronous program link call, with
notification by semaphore
(ECI_ASYNC_NOTIFY_SEM) . . . . . 162
Asynchronous status call, with
notification by message
(ECI_STATE_ASYNC_MSG) . . . . . 162
Asynchronous status call, with
notification by semaphore
(ECI_STATE_ASYNC_SEM) . . . . . 162
Fields to support ECI extensions . . . . . 163
Reply message formats . . . . . . . . 164
ECI return notification . . . . . . . . 164
Summary of input parameter requirements 164
Appendix B. Sample Programs . . . . 167
Appendix C. ECI and EPI exits. . . . . 169
Installing the exits . . . . . . . . . 169
Writing your own user exits . . . . . . 171
How the exit routines are described in the
reference sections . . . . . . . . . . 171
ECI exits reference . . . . . . . . . 171
Identification token . . . . . . . . 172
EPI exits reference . . . . . . . . . 184
CICS_EpiInitializeExit . . . . . . . 186
CICS_EpiTerminateExit . . . . . . . 187
CICS_EpiAddTerminalExit . . . . . . 188
CICS_EpiTermIdExit . . . . . . . . 191
CICS_EpiTermIdInfoExit . . . . . . 192
|
|
CICS_EpiStartTranExit . . . . . . . 193
CICS_EpiReplyExit . . . . . . . . 195
CICS_EpiDelTerminalExit . . . . . . 196
CICS_EpiGetEventExit . . . . . . . 197
CICS_EpiSystemIdExit . . . . . . . 199
CICS_EpiTranFailedExit. . . . . . . 201
Diagnostic information . . . . . . . . 203
CICSTERM, CICSPRNT and the EPI exits 203
The product library and related literature 209
CICS Transaction Gateway books . . . . 209
Sample configuration documents. . . . . 210
Redbooks . . . . . . . . . . . . 211
Other Useful Books . . . . . . . . . 211
CICS Transaction Server publications . . 211
Microsoft ® Windows Family publications 212
APPC-related publications . . . . . . 212
TCP62–related publications . . . . . 213
Obtaining books from IBM. . . . . . . 213
Accessibility . . . . . . . . . . . 215
Documentation . . . . . . . . . . 215
Glossary . . . . . . . . . . . . 217
Index . . . . . . . . . . . . . 229
Notices . . . . . . . . . . . . . 239
Trademarks . . . . . . . . . . . . 241
Sending your comments to IBM . . . . 243
Contents v

vi CICS Transaction Gateway: Programming Guide

About this book
This book is an introduction to programming for the CICS Transaction
Gateway. It provides the information that you need to allow non-CICS
applications to use CICS facilities in a client/server environment.
The book is in two parts:
Part 1, “Language independent
information” on page 1
Part 2, “Language Specific information”
on page 37
The interfaces described in this book are:
v External call interface (ECI)
v External presentation interface (EPI)
v External security interface (ESI)
Who should read this book
This provides general,
language-independent information about
the interfaces.
This provides information about the
interfaces for each supported language
(Java , C++, C, COM).
See also CICS Transaction Gateway: Programming Reference, SC34-6140.
This book is intended for anyone involved with programming a CICS
Transaction Gateway.
It is assumed that you are familiar with the operating system under which
your CICS Transaction Gateway runs.
An understanding of Internet terminology is helpful.
Conventions and terminology used in this book
A number of parts, both internal and external to the CICS Transaction
Gateway, are used when creating a business solution using the product.
Figure 1 on page viii shows some of the possible scenarios you will encounter,
and the terminology used in each case.
© Copyright IBM Corp. 2002 vii

Distributed platforms running in remote mode
Java client
application
z/OS running in local mode
Java client
application
Gateway
classes
Gateway
classes
CICS
server
Gateway
daemon
Distributed platforms running in local mode
Java client
application
Gateway
classes
Client
daemon
Distributed platforms running non-Java applications
Client
application
Client
daemon
z/OS running in remote mode
Java client
application
Gateway
classes
CICS
server
Gateway
daemon
Client
daemon
CICS
server
CICS
server
Figure 1. CICS Transaction Gateway uses, with their associated terminology
CICS
server
The following explains the terms used in Figure 1:
Gateway daemon
Used only in remote mode, the Gateway daemon listens on protocols
defined in CTG.INI for gateway requests from remote Java client
applications. It issues these requests to the Client daemon on
distributed platforms, and directly to CICS over the EXCI on z/OS ® .
The Gateway daemon runs the protocol listener threads, the worker
threads and the connection manager threads. It uses the GATEWAY
section of CTG.INI (and on z/OS the ctgenvvar script) for its
configuration.
Client daemon
The Client daemon (process cclclnt) exists only on distributed
platforms. 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.
viii CICS Transaction Gateway: Programming Guide

Gateway classes
The interface for Java Client applications to connect to the Gateway
daemon. The Gateway classes, which are supplied with the CICS
Transaction Gateway, must be in the classpath for Java Client
applications to run.
Client application
A user application, written in a supported programming language
other than Java, that communicates directly with the Client daemon.
Java Client application
A Java application, servlet or applet that communicates with the
Gateway classes.
Installation path
The term is used in file paths to represent the directory where
you installed the product. See the CICS Transaction Gateway: Administration
book for your operating system, for the default installation locations.
Directory delimiters
References to directory path names in this book use the Microsoft ® Windows ®
convention of a backslash (\) as delimiter, instead of the forward slash (/)
delimiter used on z/OS and UNIX ® operating systems.
Programming language specific
The term C refers to both the C and C++ programming languages.
Operating system specific
Unless otherwise specified, the term Windows refers to Windows NT ® ,
Windows 2000, and Windows XP.
The term Windows 2000 Terminal Server means a server with the Terminal
Services feature installed.
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.
About this book ix

x CICS Transaction Gateway: Programming Guide

|
|
Summary of changes
This book contains material that previously appeared in these books:
v CICS Transaction Gateway Gateway Programming, SC34-5938
v CICS Transaction Gateway C++ Programming, SC34-5945
v CICS Transaction Gateway COM Automation Programming, SC35-5946
v CICS Family Client/Server Programming, SC34-5947
Vertical lines at the left side of the page indicate material that is new to this
edition.
The following functional changes have been made for CICS Transaction
Gateway Version 5.0:
v The Windows XP operating system is supported.
v COBOL is supported on the Windows operating system.
Some beans that were previously provided as part of the CICS Transaction
Gateway product are now, instead, included with the set of sample programs.
See “Beans provided in earlier versions of CICS Transaction Gateway” on
page 101 for details.
© Copyright IBM Corp. 2002 xi

xii CICS Transaction Gateway: Programming Guide

Part 1. Language independent information
© Copyright IBM Corp. 2002 1

2 CICS Transaction Gateway: Programming Guide

Chapter 1. Getting started
Overview
ECI, EPI, and ESI allow your non-CICS applications to access CICS facilities
and data.
Figure 2 illustrates the use of the external interfaces by a non-CICS application
in a client system. This application is using the facilities of CICS in a server
system. CICS Transaction Gateway processes the application’s ECI and EPI
requests, and transmits them to the server system using an appropriate
communication protocol. Although the figure shows the client system and
server system as separate workstations, it is possible for the whole
configuration to be on a single workstation.
Client system Server system
Application
ECI
EPI
CICS
Transaction
Gateway
Figure 2. External access interfaces in a CICS client/server configuration
External Call Interface (ECI)
ECI allows a non-CICS application to call a CICS program in a CICS server.
The application can connect to several servers at the same time, and there can
be several program calls outstanding at the same time.
CICS
The CICS program cannot perform terminal I/O, but can access and update
all other CICS resources.
Figure 3 on page 4 shows that the same CICS program can be called by a
non-CICS application using ECI, or by a CICS program using EXEC CICS LINK.
Data passes between the two programs using a COMMAREA, in a similar
way to CICS interprogram communication.
© Copyright IBM Corp. 2002 3

Application
Figure 3. ECI illustrated
ECI
CICS
CICS
CICS program
EXEC CICS LINK ...
CICS programs
Calls can be made synchronously or asynchronously:
v Synchronous calls return control when the called program completes, and
the information returned is immediately available.
v Asynchronous calls return control without waiting for the called program to
complete, and the application can ask to be notified when the information
becomes available.
Calls can also be extended. That is, a single logical unit of work may cover two
or more successive calls, though only one call can be active for each logical
unit of work at any time. The application can manage many logical units of
work concurrently if it uses asynchronous calls.
The called program can update resources on its own system, and can use
distributed program link (DPL) to call CICS programs on other systems. It can
access resources on other CICS systems by function shipping, by distributed
transaction processing (DTP), or by the front end programming interface
(FEPI).
External Presentation Interface (EPI)
EPI allows a non-CICS application program to be viewed as a 3270 terminal
by a CICS server system to which it is connected. Figure 4 on page 5 shows
how both an EPI application and a CICS terminal can schedule transactions in
a CICS server.
4 CICS Transaction Gateway: Programming Guide
Data

Application
EPI
CICS
Figure 4. External presentation interface
CICS transactions
The application can use the facilities of several servers at the same time, and
can act as if it were many different 3270 terminals.
The application can schedule CICS transactions, and for these transactions it is
the principal facility.
With CICS servers that support access through the EPI, other CICS
transactions running in the server can use the CICS START command to
schedule transactions that use the non-CICS application as their initiating
terminal.
When a non-CICS application uses the EPI to start a transaction in a CICS
server, 3270 data streams and events are passed between the server and the
application. The application can present the contents of the terminal I/O to its
user in any manner appropriate to the application’s operating environment.
Transactions can be routed to other CICS systems by standard transaction
routing. Resources on other CICS systems can be accessed by function
shipping.
External Security Interface (ESI)
ESI allows a non-CICS application to invoke services provided by advanced
program-to-program communication (APPC) password expiration
management (PEM).
Data
Chapter 1. Getting started 5

APPC PEM with CICS provides support for an APPC sign-on transaction that
signs on userids to a CICS server, and processes requests for a password
change by:
v Identifying a user and authenticating that user’s identification
v Notifying specific users during the authentication that their passwords have
expired
v Letting users change their passwords when, or before, the passwords expire
v Telling users how long their current passwords will remain valid
v Providing information about unauthorized attempts to access the server
using a particular user identifier
You can include ESI calls in your ECI or EPI applications.
Using the external access interfaces
The external interfaces allow non-CICS applications to access and update
CICS resources by initiating CICS transactions or calling CICS programs.
When used in conjunction with the CICS communication facilities, they enable
non-CICS programs to access and update resources on any CICS system. This
supports such activities as:
1. Developing graphical user interface (GUI) front ends for CICS
applications, using Presentation Manager ® or other presentation systems
2. Connecting external devices such as bar-code readers to CICS systems
3. Allowing the integration of CICS systems and non-CICS systems.
EPI allows you to develop GUIs, either for existing CICS systems or for new
applications. It is particularly useful for developing new GUI front ends for
existing CICS transactions, which need not be changed. The application can
use EPI to communicate with a CICS transaction, and can exploit the
presentation facilities of the client system to communicate with the user.
If you attach an external device, such as a bar code reader, the application can
deal with device input and output, and can use the EPI to start a transaction,
perhaps one already written to deal with the kind of data that the external
device produces. The application converts the input from the external device
into a 3270 data stream to start the transaction and pass the data to it. Output
from the transaction, in the form of a 3270 data stream, is then converted into
the signals and data streams that operate the external device.
You can use both EPI and ECI to pass data between a non-CICS application
and a CICS program. However, the methods are different:
v EPI uses 3270 data streams
v ECI uses application-defined formats in a COMMAREA
6 CICS Transaction Gateway: Programming Guide

ECI and EPI exits
For CICS Transaction Gateway, the operation of the EPI and ECI can be
customized by the user exits described in Appendix C, “ECI and EPI exits” on
page 169.
Support for object-oriented programming
The principal communication mechanism that CICS Transaction Gateway
provides is the External Call Interface (ECI). The supplied ECI class library,
modelling the full function of ECI in an object-oriented way, allows you to:
v make links to servers
v make calls to CICS programs on servers
v check status
v use units of work (UOW’s)
The second interface available to application programmers on CICS
Transaction Gateway is the External Presentation Interface (EPI). EPI provides
communication with 3270 terminal based CICS applications using classes
encapsulating terminals, screens, fields and BMS maps. EPI classes make it
unnecessary to work directly with the 3270 datastream, and make it easier to
examine and update the contents of an output screen.
Chapter 1. Getting started 7

Support for object-oriented programming
8 CICS Transaction Gateway: Programming Guide

Chapter 2. External Call Interface (ECI)
Overview
This chapter describes the External Call Interface (ECI).
Although the interface is described in a way that is independent of
programming language, the names used for elements of the interface are
similar to those used in programming.
Information that is specific to programming languages is in the following
chapters:
v Chapter 5, “Programming in C and COBOL” on page 39
v Chapter 6, “Programming in C++” on page 45
v Chapter 7, “Programming in Java” on page 73
v Chapter 8, “Programming using J2EE” on page 115
v Chapter 9, “Programming in COM” on page 137
Some ECI functions are dependent on the operating system. These are
described in Appendix A, “ECI extensions that are environment-dependent”
on page 161.
The Chapter is organized as follows:
“Overview”
“Program link calls” on page 12
“Status information calls” on page 15
“Reply solicitation calls” on page 17
ECI function
ECI allows a non-CICS application program to call a CICS program in a CICS
server. The non-CICS application does not issue any CICS commands itself;
the CICS commands are issued by the called program running in the server.
This means the called program appears to have been called by the EXEC CICS
LINK command with the COMMAREA option. An ECI application can make use of
existing CICS programs, or you can write new CICS programs to be called by
ECI applications. The called programs must follow the rules for CICS
programs called by DPL.
An application can run more than one CICS program concurrently, and these
programs might be distributed across several CICS servers.
© Copyright IBM Corp. 2002 9

External Call Interface (ECI)
The function provided by ECI is packaged in two parts:
CICS_ExternalCall Provides most of the function of ECI. It has a
single parameter, the ECI parameter block, in
which various fields describe the function to
be performed and the inputs and outputs.
Most of the following sections are concerned
with the use of CICS_ExternalCall.
CICS_EciListSystems Used to find out about available servers to
which CICS_ExternalCall requests can be
directed.
Types of ECI call
There are three types of call to CICS_ExternalCall:
v Program link calls
v Status information calls
v Reply solicitation calls.
The type of call to CICS_ExternalCall is determined by the setting of the
eci_call_type parameter in the ECI parameter block.
Restrictions on call type for particular operating environments are discussed
in the descriptions of each call type.
Program link calls
Program link calls cause a CICS program to be executed on a CICS server.
These calls can be:
Synchronous The application waits until the called program has finished.
Returned information is immediately available.
Asynchronous The application gets back control without waiting for
completion of the called program. The application can ask to
be notified later when the information is available. It must use
a reply solicitation call to determine the outcome of the
asynchronous request.
Status information calls
Status information calls retrieve status information about the type of system
on which the application is running and its status. These calls can be:
Synchronous The application waits until the information has been made
available.
Asynchronous The application gets back control while the information is
being retrieved. The application can ask to be notified later
when the information is available. It must use a reply
solicitation call to determine the outcome of the asynchronous
request.
10 CICS Transaction Gateway: Programming Guide

External Call Interface (ECI)
Reply solicitation calls
Reply solicitation calls get information back after asynchronous program link
or asynchronous status information calls. Reply solicitation calls can be:
General Retrieving any piece of outstanding information.
Specific Retrieving information for a named asynchronous request.
An application that uses the asynchronous method of calling may have
several program link and status information calls outstanding at any time.
The eci_message_qualifier parameter in the ECI parameter block can be used
on an asynchronous call to provide a user-defined identifier for the call. The
use of different identifiers for different asynchronous calls within a single
application is the programmer’s responsibility. When a general reply
solicitation call is made, ECI uses the eci_message_qualifier field to return
the name of the call to which the reply belongs. When a specific reply
solicitation call is made, you must supply a value in the
eci_message_qualifier field to identify the asynchronous call about which
information is being sought.
Time-outs
The support consists of a field eci_timeout in the ECI parameter block, and
two return codes: ECI_ERR_RESPONSE_TIMEOUT and
ECI_ERR_REQUEST_TIMEOUT.
In the processing of timeouts, there are two cases to consider.
v The time-out occurs before the request has been forwarded to the server. In
this case the response is ECI_ERR_REQUEST_TIMEOUT. The requested
program was not called, and no server resources have been updated.
– If the call was intended to start, or be the whole of, a new logical unit of
work, the logical unit of work was not started, and no recoverable
resources have been updated.
– If the call was intended to continue an existing logical unit of work, the
logical unit of work was continued, but no recoverable resources were
updated, and the logical unit of work is still uncommitted.
– If the call was intended to end an existing logical unit of work, the
logical unit of work was continued, no recoverable resources were
updated, and the logical unit of work is still uncommitted.
v The time-out occurs after the request has been forwarded to the server. In
this case the response is ECI_ERR_RESPONSE_TIMEOUT, and it could be
returned to a synchronous call, or to an asynchronous call, or to the reply
solicitation request that gets the reply to an asynchronous call.
– If the call was intended to be the only call of a new logical unit of work,
the logical unit of work was started, but it is not possible for the
application to determine whether updates were performed, and whether
they were committed or backed out.
Chapter 2. External Call Interface (ECI) 11

External Call Interface (ECI)
– If the call was intended to end an existing logical unit of work by using
ECI_NO_EXTEND, the logical unit of work has ended, but it is not
possible for the application to determine whether updates were
performed, and whether they were committed or backed out.
– If the call was intended to continue or to end an existing logical unit of
work by using ECI_COMMIT, the logical unit of work persists, and
changes to recoverable resources are still pending.
Program link calls
Program link calls can be either synchronous or asynchronous. For
asynchronous calls, it is the responsibility of the calling application to solicit
the reply using one of the reply solicitation calls. (See “Reply solicitation calls”
on page 17.)
Managing logical units of work
An ECI application is often concerned with updating recoverable resources on
the server, and the application programmer needs to understand the facilities
that ECI provides for managing logical units of work. A logical unit of work is
all the processing in the server that is needed to complete a set of changes to
recoverable resources. When the logical unit of work ends normally, the
changes will all be committed. When the logical unit of work ends
abnormally, for instance because a program abends, the changes are all backed
out. You can use ECI to start and end logical units of work on the server.
The changes to recoverable resources in a logical unit of work might be made
by:
v A single program link call, or
v A sequence of program link calls
On successful return from the first of a sequence of calls for a logical unit of
work, the eci_luw_token field in the control block contains a token that
should be used for all later calls related to the same logical unit of work. All
program link calls for the same logical unit of work will be sent to the same
server.
Note: Take care when extending a logical unit of work across multiple
program link calls that may span a long period of time, for example,
user thinking time. The reason is that the logical unit of work holds
various locks and other CICS resources on the server, and this may
cause delays to other users who are waiting for those same locks and
resources.
When a logical unit of work ends, the CICS server attempts to commit the
changes. The last, or only, program link call of a logical unit of work is
advised whether the attempt was successful.
12 CICS Transaction Gateway: Programming Guide

Only one program link call per logical unit of work can be outstanding at any
time. (An asynchronous program link call is outstanding until a reply
solicitation call has processed the reply.)
Table 1 shows how you can use combinations of eci_extend_mode,
eci_program_name, and eci_luw_token parameter values to perform tasks
associated with managing logical units of work through ECI. In each case you
must also store appropriate values in other fields for the call type you have
chosen.
Table 1. Logical units of work in ECI
Task to perform Parameters to use
Call a program that is to be the only program of a Set up the parameters as follows:
logical unit of work.
v eci_extend_mode: ECI_NO_EXTEND
One request flows from client to server and a v eci_program_name: provide it
reply is sent to the client only after all the changes
made by the specified program have been
committed.
v eci_luw_token: zero
Call a program that is to start a new logical unit of
work that is to be extended.
Call a program that is to continue an existing
logical unit of work.
Call a program that is to be the last program of an
existing logical unit of work, and commit the
changes.
End an existing logical unit of work, without
calling another program, and commit changes to
recoverable resources.
End an existing logical unit of work, without
calling another program, and back out changes to
recoverable resources.
External Call Interface (ECI)
Set up the parameters as follows:
v eci_extend_mode: ECI_EXTENDED
v eci_program_name: provide it
v eci_luw_token: zero
Afterwards, save the token from eci_luw_token.
Set up the parameters as follows:
v eci_extend_mode: ECI_EXTENDED
v eci_program_name: provide it
v eci_luw_token: provide it
Set up the parameters as follows:
v eci_extend_mode: ECI_NO_EXTEND
v eci_program_name: provide it
v eci_luw_token: provide it
Set up the parameters as follows:
v eci_extend_mode: ECI_COMMIT
v eci_program_name: null
v eci_luw_token: provide it
Set up the parameters as follows:
v eci_extend_mode: ECI_BACKOUT
v eci_program_name: null
v eci_luw_token: provide it
If an error occurs in one of the calls of an extended logical unit of work, you
can use the eci_luw_token field to see if the changes made so far have been
backed out, or are still pending. See the description of the eci_luw_token field
Chapter 2. External Call Interface (ECI) 13

External Call Interface (ECI)
in CICS Transaction Gateway: Programming Reference for more information. If the
changes are still pending, you should end the logical unit of work with
another program link call, either committing or backing out the changes.
Each logical unit of work (LUW) 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.
Figure 5 shows an application program using asynchronous program calls.
The program has two calls outstanding in one server and one call in another.
To keep track of its requests, the program is using message qualifiers that it
has generated itself, and LUW tokens returned in the eci_luw_token field. The
LUW token is unique for each call.
Server 1
Message qualifiers
LUWtokens
Application
CICS programs CICS program
Figure 5. Asynchronous program link calls with message qualifiers and LUW tokens
Server 2
For more details of the program link calls, study the descriptions of the
individual call types:
ECI_SYNC for a synchronous program link call
ECI_ASYNC for an asynchronous program link call.
14 CICS Transaction Gateway: Programming Guide

Security in the ECI
The ECI_SYNC and ECI_ASYNC calls are implemented as a set of
intersystem conversations between a Client daemon and a CICS server; a
conversation is allocated for each unit of work created by the client
application.
Status information calls
External Call Interface (ECI)
A userid and password might be required for each intersystem conversation;
the requirement is determined by the way in which the Client daemon and
CICS server have been configured.
The client application can specify the userid and password in the eci_userid
(or eci_userid2) and eci_password (or eci_password2) in the ECI parameter
block for the first or only call in the unit of work.
The client application can pass the userid and password to the
CICS_SetDefaultSecurity function. The values are server-specific and are used
whenever the values have been omitted from the ECI parameter block. The
values can be changed at any time by the CICS_SetDefaultSecurity function.
If the userid and password are required for intersystem conversations, and
they are not set by the CICS_SetDefaultSecurity function, the Client daemon
might use another method, for example opening a pop-up window, to request
them.
For more information on how to configure client/server security on UNIX or
Windows, see Client Security, inCICS Transaction Gateway: UNIX Administration
or CICS Transaction Gateway: Windows Administration.
Status information calls can be either synchronous or asynchronous. For
asynchronous calls, it is the responsibility of the calling application to obtain
the reply using a reply solicitation call (see “Reply solicitation calls” on
page 17).
How status information is supplied and used
Status information is supplied in the ECI status block, which is passed across
the interface in the eci_commarea parameter.
The following status information is held in the ECI status block.
Type of connection Whether the ECI program is locally connected
to a CICS server, to a CICS Transaction
Gateway, or to nothing.
State of the CICS server Available, unavailable, or unknown.
Chapter 2. External Call Interface (ECI) 15

External Call Interface (ECI)
State of CICS Transaction Gateway
Available, not applicable, or unknown.
For a more detailed description of the ECI status block, refer to CICS
Transaction Gateway: Programming Reference.
The status information calls allow you to perform three tasks:
Enquire on the type of system the application is running on, and its
connection with a given server.
For this you need to provide a COMMAREA in
which the status is returned.
Set up a request to be notified when the status changes from some
specified value. For this you need to provide a COMMAREA in
which the specified status is described. When
the status is different from the status specified,
you are notified of the new status. Only
asynchronous calls can be used for this
purpose.
Cancel a request for notification of status change.
For this no COMMAREA is required.
Table 2 shows how you can use combinations of eci_extend_mode,
eci_commarea, eci_commarea_length, and eci_luw_token parameter values to
perform tasks associated with status enquiries. In each case you must also
store appropriate values in other fields for the call type you have chosen.
For more details of the status information calls, see the descriptions of the
individual call types in CICS Transaction Gateway: Programming Reference:
ECI_STATE_SYNC
For a synchronous status information call
ECI_STATE_ASYNC
For an asynchronous status information call.
Table 2. Status enquiries with CICS_ExternalCall
Task to perform Parameters to use
Find the current status. Set up the parameters as follows:
v eci_commarea: nulls
v eci_commarea_length: length of ECI_STATUS
v eci_extend_mode: ECI_STATE_IMMEDIATE
16 CICS Transaction Gateway: Programming Guide
Afterwards, consult the contents of the
COMMAREA to find the status.

Table 2. Status enquiries with CICS_ExternalCall (continued)
Task to perform Parameters to use
Set up a request to find out about status change. Set up the parameters as follows:
v eci_commarea: specified status
v eci_commarea_length: length of ECI_STATUS
v eci_extend_mode: ECI_STATE_CHANGED
v eci_luw_token: zero
Afterwards, save the token from eci_luw_token so
that you can cancel the request later.
Cancel a request to find out about status change. Set up the parameters as follows:
v eci_commarea: none
v eci_commarea_length: zero
v eci_extend_mode: ECI_STATE_CANCEL
v eci_luw_token: provide it
Reply solicitation calls
External Call Interface (ECI)
After an asynchronous program link call, or asynchronous status information
call, it is the responsibility of the calling application to solicit the reply. All
calls return any outstanding reply that meets the selection criteria specified in
the call.
For more details of the reply solicitation calls, see the descriptions of the
individual call types in CICS Transaction Gateway: Programming Reference:
ECI_GET_REPLY For a reply solicitation call that gets any
outstanding reply for any asynchronous call, if
any reply is available.
ECI_GET_REPLY_WAIT For a reply solicitation call that gets any
outstanding reply for any asynchronous call,
waiting if no replies are available.
ECI_GET_SPECIFIC_REPLY For a reply solicitation call that gets any
outstanding reply for a given asynchronous
call, if any reply is available.
ECI_GET_SPECIFIC_REPLY_WAIT
For a reply solicitation call that gets any
outstanding reply for a given asynchronous
call, waiting if no replies are available.
Chapter 2. External Call Interface (ECI) 17

External Call Interface (ECI)
18 CICS Transaction Gateway: Programming Guide

Chapter 3. External Presentation Interface (EPI)
Overview
This chapter describes the External Presentation Interface (EPI).
Although the interface is described in a way that is independent of
programming language, the names used for elements of the interface are
similar to those used in programming.
Information that is specific to programming languages is in the following
chapters:
v Chapter 5, “Programming in C and COBOL” on page 39
v Chapter 6, “Programming in C++” on page 45
v Chapter 7, “Programming in Java” on page 73
v Chapter 8, “Programming using J2EE” on page 115
v Chapter 9, “Programming in COM” on page 137
The chapter is organized as follows:
“Overview”
“How to use EPI” on page 20
“3270 data streams for the EPI” on page 30
EPI allows a non-CICS application program to have access to one or more
CICS servers. In each CICS server, the application can establish one or more
terminal resources. The application acts as the operator of these terminal
resources, starting CICS transactions, and sending and receiving standard 3270
data streams associated with those transactions.
Consider the following when you design client/server implementations using
EPI.
v A CICS transaction that sends data to an EPI application must not use basic
mapping support (BMS) paging.
v An EPI application can use EPI to determine the default screen size of the
terminal resource definition, but not the alternate screen size.
v An EPI application cannot use EPI to determine whether it is to send or
receive double byte character set (DBCS) data streams to or from the CICS
transaction.
v The 3270 data streams produced by CICS transactions must not contain
structured fields.
© Copyright IBM Corp. 2002 19

External Presentation Interface (EPI)
How to use EPI
v For EPI terminals on CICS Transaction Gateway, the maximum screen size
is 27 rows by 132 columns. This is because the CICS Transaction Gateway
supports the ASCII-7 subset of the 3270 data stream architecture, which
only supports 12 bit addressing. For more information, see “3270 data
streams for the EPI” on page 30.
v If a CICS transaction uses EXEC CICS START with the DELAY option to
schedule transactions to a terminal resource autoinstalled by an EPI
application, the EPI application should take care when deleting the terminal
resource, or delayed ATI requests might be lost. See your server
documentation to determine the effects of deleting a terminal resource
when delayed ATI requests are outstanding.
The application is responsible for the presentation of the 3270 data received.
The application may present the data in the normal way by emulating a 3270
terminal, or it may present a very different view. For example:
v A Windows application might use the Windows graphical user interface.
v A Solaris application might use Open Look.
Initialization and termination
Any application that needs to use EPI must call the CICS_EpiInitialize
function to initialize EPI. Until this call is made, no other EPI function is
allowed. The CICS_EpiInitialize function takes a parameter indicating the
version of the EPI for which the application was coded. This is to ensure that
existing applications continue to run without change if the EPI is extended.
See “EPI versions” on page 29 for more details.
Before an EPI application ends, it should call the CICS_EpiTerminate function
to terminate EPI cleanly.
Listing the configured servers
After calling CICS_EpiInitialize successfully, the application should call
CICS_EpiListSystems to check which CICS servers are configured for use by
the application.
Adding terminal resources
The primary purpose of EPI is to allow an application to appear to a CICS
server as one or more 3270 terminals.
Terminal resources are added by invoking either the CICS_EpiAddTerminal
or CICS_EpiAddExTerminal function.
An application can specify the server in which the terminal resource is to be
installed; if it does not the default server is selected.
20 CICS Transaction Gateway: Programming Guide

External Presentation Interface (EPI)
An application can specify the terminal resource to be installed by supplying
one of the following:
The netname of an existing terminal resource in the server
This terminal resource should be one that is
not currently in use.
The name of a model terminal definition
In this case, the server generates a netname
and autoinstalls a terminal resource with that
netname, using the specified model terminal
definition.
Nothing In this case the server generates a netname
and autoinstalls a terminal resource with that
name, using a default model terminal
definition.
When an application has installed a terminal resource, no other application
can use that terminal resource until the first application deletes it.
The CICS_EpiAddTerminal and CICS_EpiAddExTerminal functions return a
terminal index, which must be passed on subsequent EPI function calls to
indicate the terminal resource to which the function is to apply. Each index
identifies a combination of server and terminal resource. The terminal index
supplied is the first available integer starting from 0. This allows the
application to maintain a mapping between terminal indexes and terminal
resource information, using array lookup.
Terminal indexes are unique within an application, but not across
applications, so each application gets terminal index zero for the first terminal
it installs, and so on.
Figure 6 on page 22 shows an application with three terminal resources, one in
one server and two in another. The application uses the terminal indexes to
operate the terminal resources, sending and receiving 3270 data streams.
Chapter 3. External Presentation Interface (EPI) 21

External Presentation Interface (EPI)
Server 1
Terminal resources
Figure 6. Using terminal indexes
Application
Terminal indexes
0 1 2
Terminal resource
Server 2
Terminal attributes
Most attributes are determined by the server when the terminal resource is
installed; some are returned to the application in the CICS_EpiDetails_t
structure passed to the CICS_EpiAddTerminal and CICS_AddExTerminal
functions.
Some attributes might be determined by the application. These attributes are
specified in the CICS_EpiAttributes_t structure passed to the
CICS_EpiAddExTerminal function. For example the character set and
encoding scheme to be used for 3270 data is specified in the CCSID field in the
CICS_EpiAttributes_t structure. For more details on the
CICS_EpiAttributes_t structure refer to its entry in the EPI constants and data
structures section in the CICS Transaction Gateway: Programming Reference
manual.
Timeout
Execution of the CICS_EpiAddTerminal function is synchronous; execution of
the CICS_EpiAddExTerminal function can be asynchronous. Control is not
returned to the invoking application until a response, for example, that the
terminal resource has been installed, is available.
22 CICS Transaction Gateway: Programming Guide

External Presentation Interface (EPI)
The response time depends on a number of factors; for example:
v Network parameters and traffic
v Server parameters and transaction load
An application can limit the length of time that it will wait for a response; the
limit is specified in the InstallTimeOut field in the CICS_EpiAttributes_t
structure passed to the CICS_EpiAddExTerminal function.
If the CICS Transaction Gateway does not receive a response from the server
within the specified interval, control will be returned to the invoking
application with the return code set to CICS_EPI_ERR_RESPONSE_TIMEOUT.
If the Client daemon is subsequently notified that the terminal resource has
been installed in the server, the Client daemon will delete the terminal
resource. Note that this action has the effect of increasing the network traffic
and the transaction load on the server.
Deleting terminal resources
If a terminal resource is no longer required, it can be deleted by invoking
either the CICS_EpiDelTerminal or CICS_EpiPurgeTerminal function.
The CICS_EpiDelTerminal function is used when the terminal resource is to
be deleted in a controlled manner. The call succeeds only if no transaction is
running against the terminal resource and there are no unprocessed events for
the terminal resource; if a transaction is in progress or there are unprocessed
events, the call returns an error code.
The CICS_EpiPurgeTerminal function is used when the terminal resource is
to be deleted without regard to a transaction that may be running against the
terminal or unprocessed events for the terminal resource.
When the terminal resource has been deleted the terminal index value
becomes free and can be reused when another terminal resource is added. The
server deletes the terminal resource if it was autoinstalled.
Authentication and authorization
When an application has defined a terminal resource, it can start transactions
from that terminal resource. The server may have to:
v Authenticate the userid and password for the terminal ″operator″
v Grant authority, based on the authenticated userid, to access the resources
required for the execution of each transaction.
Chapter 3. External Presentation Interface (EPI) 23

External Presentation Interface (EPI)
The frequency with which the userid and password are authenticated by the
server depends on another attribute specified in the SignOnCapability field
in the CICS_EpiAttributes_t structure passed to the CICS_EpiAddExTerminal
function.
Signon capable terminals
If the terminal resource is installed as signon capable, the application is
responsible for starting a signon transaction, for example the CICS supplied
CESN transaction; the userid and password being embedded in the 3270 data.
Transactions started before the signon transaction will execute with the
authorities granted to a default userid. Transactions started after the signon
transaction will execute with the authorities granted to the authenticated
userid.
A consequence of installing a terminal as signon capable is that the
application must be prepared to cope with the ″operator″ being signed off if
the terminal resource remains idle for longer than a server defined limit.
Signon incapable terminals
If the terminal resource is installed as signon incapable, the userid and
password are authenticated for each transaction started for the terminal
resource. The initial userid and password for the terminal resource may be
specified in the UserId and Password fields in the CICS_EpiAttributes_t
structure passed to the CICS_EpiAddExTerminal function.
The userid and password may be changed at any time by invoking the
CICS_EpiSetSecurity function.
For information on how to provide a userid and password, on UNIX or
Windows, see Client Security, inCICS Transaction Gateway: UNIX Administration
or CICS Transaction Gateway: Windows Administration.
Starting transactions
When an application has defined a terminal resource, it can start a transaction
from that terminal resource. To the CICS server it appears as if a terminal user
had typed a transaction code on the screen and pressed an AID key. To start a
transaction, the CICS_EpiStartTran function is called. There are two ways of
specifying the transaction to be started and the data to be associated with it.
1. Supply the transaction identifier as a parameter to the call (TransId), and
supply any transaction data in the Data parameter.
2. Combine a transaction identifier and transaction data into a 3270 data
stream, and supply the data stream as a parameter to the call (Data).
Events and callbacks
When an application has defined a terminal resource, several events can
happen to it because of actions in the CICS server, rather than actions of the
24 CICS Transaction Gateway: Programming Guide

External Presentation Interface (EPI)
application. The application cannot predict when those events may happen,
but it is the responsibility of the application to collect and process the events
as appropriate. Events are held by the EPI in a first-in-first-out queue until
they are collected, one by one, by the application making calls to the
CICS_EpiGetEvent function. During such a call, the EPI puts information in a
CICS_EpiEventData_t structure to indicate the event that occurred and any
associated data. It also indicates whether there are more events still waiting in
the queue.
The application can synchronize the processing of these events with its other
activities in one of three ways:
v Polling
v Blocking
v Callback notification.
Polling
The CICS_EpiGetEvent call can be made in a polling mode by specifying
CICS_EPI_NOWAIT for the Wait parameter. If no event is waiting to be
collected, the function returns immediately with an error code. This is the
mechanism that you would have to adopt in a single-user single-threaded
environment, where the application might alternately poll the keyboard for
user activity and poll the EPI for event activity.
Blocking
The CICS_EpiGetEvent call can be made in a blocking mode by specifying
CICS_EPI_WAIT for the Wait parameter. If no event is waiting to be collected,
the function waits and does not return until an event becomes available. You
could use this mechanism in a multithreaded environment, where a secondary
thread could be dedicated to event processing. It could also be used after a
notification by callback, because the event information is known to be
available.
Callback notification
When the terminal resource is defined with the CICS_EpiAddTerminal or
CICS_EpiAddExTerminal call, the optional parameter NotifyFn may be used
to provide the address of a callback routine that the EPI calls whenever an
event occurs against that terminal resource.
Note: Some compilers do not support the use of callback routines. Consult
your compiler documentation for more information.
An application should carry out the minimum of processing in its callback
routine, and never block in the specified routine before returning to the EPI.
The routine itself cannot make EPI calls. You decide what it should do when
the notification is received. For example, in a multithreaded environment, it
might post a semaphore to signal another thread that an event has occurred.
Chapter 3. External Presentation Interface (EPI) 25

External Presentation Interface (EPI)
In a Presentation Manager environment, it might post a message to a window
to indicate to the window procedure that an event has occurred. Other actions
will be appropriate for other environments.
When the callback routine is called, it is passed a single parameter—the
terminal index of the terminal resource against which the event occurred. This
allows the same callback routine to be used for more than one terminal
resource.
Processing the events
On return from the CICS_EpiGetEvent function, the CICS_EpiEventData_t
structure contains the details of the event that occurred. The Event field in
this structure indicates the event, and can take one of the following values:
v CICS_EPI_EVENT_SEND
v CICS_EPI_EVENT_CONVERSE
v CICS_EPI_EVENT_END_TRAN
v CICS_EPI_EVENT_START_ATI
v CICS_EPI_EVENT_ADD_TERM
v CICS_EPI_EVENT_END_TERM
The application should attempt to process events as quickly as possible,
because some events describe the state of the terminal resource. If these events
are not processed, the application may receive unexpected error return codes
when it tries to issue EPI functions, because the state maintained inside the
EPI might not match the state maintained in the application. For example, an
application can start a transaction only if the terminal resource is not currently
running another transaction. The CICS_EPI_EVENT_END_TRAN event
signals the end of a transaction, and so the application and the EPI enter a
state in which new transactions can be started for that terminal resource. The
CICS_EPI_EVENT_START_ATI event indicates that an ATI transaction has
started at the terminal resource, and therefore that the terminal resource has
entered a state in which the starting of transactions is no longer allowed. If
the application calls CICS_EpiStartTran after the
CICS_EPI_EVENT_START_ATI event has been notified, but before the event
has been retrieved, the CICS_EpiStartTran call fails, even though, to the
application, it may appear that it is still in a state in which it should succeed.
When a client application is driven with an event or callback, it should issue a
CICS_EpiGetEvent to get the associated event. In certain timing conditions,
the CICS_EPI_EVENT_START_ATI may already have been notified from a
previous CICS_EpiGetEvent. The CICS_EpiGetEvent issued after the callback
can receive CICS_EPI_ERR_NO_EVENT (if CICS_EPI_NOWAIT is specified
for the Wait parameter) or wait until a subsequent event is received (if
CICS_EPI_WAIT is specified for the Wait parameter). Note that this can
happen after a CICS_EPI_EVENT_START_ATI is received.
26 CICS Transaction Gateway: Programming Guide

External Presentation Interface (EPI)
Sending and receiving data
When a transaction sends data to a terminal resource, the EPI generates either
a CICS_EPI_EVENT_SEND event or a CICS_EPI_EVENT_CONVERSE event.
The data sent might be data from the transaction, or it might be messages
produced by the server, including error messages. You should consult your
server documentation to see what messages are possible. An EPI application
should analyze the data stream to see if an error has occurred.
The CICS_EPI_EVENT_SEND event indicates that data was sent but that no
reply is required. Typically this would result from an EXEC CICS SEND
command, but in some servers it would result from an EXEC CICS
CONVERSE command. (In the latter case, a CICS_EPI_EVENT_CONVERSE
event occurs later to tell the application to send a data stream back to the
transaction in the server.)
The CICS_EPI_EVENT_CONVERSE event indicates that a reply is required,
and would typically result from an EXEC CICS RECEIVE or EXEC CICS
CONVERSE command. The application should respond to this event by
issuing a CICS_EpiReply call to provide the response data. The
CICS_EpiReply function should be issued only to respond to a
CICS_EPI_EVENT_CONVERSE event; if it is issued at any other time, an
error is returned.
Managing pseudoconversations
CICS transactions can operate in a pseudoconversational mode. The
conversation between a terminal resource and a server is broken up into a
number of segments, each of which is a separate transaction. As each
transaction ends, it provides the name of the transaction to be run to process
the next input from the terminal resource. (It uses EXEC CICS RETURN with
the TRANSID option to do this.) The CICS_EPI_EVENT_END_TRAN event
tells the application whether the transaction just ended has specified a
transaction to process the next input, and which transaction has been
specified. The application must not attempt to start a different transaction, but
must use CICS_EpiStartTran to start the transaction specified by the
CICS_EPI_EVENT_END_TRAN event.
Security in the EPI
The EPI is implemented as a set of intersystem conversations between CICS
Transaction Gateway and server; for example, a conversation is allocated for:
v Each terminal resource that is installed; refer to the CICS_EpiAddTerminal
and CICS_EpiAddExTerminal functions.
v Each transaction that is started; refer to the CICS_EpiStartTran function.
v Each terminal resource that is deleted from the server; refer to the
CICS_EpiDelTerminal function.
Chapter 3. External Presentation Interface (EPI) 27

External Presentation Interface (EPI)
A userid and password may be required for each intersystem conversation;
the requirement is determined by the way in which CICS Transaction
Gateway and CICS server have been configured.
The client application can specify the userid and password in the
CICS_EpiAttributes_t structure passed to the CICS_EpiAddExTerminal
function. The values are terminal specific and are passed to the server in the
intersystem conversation allocated to install the terminal and in subsequent
intersystem conversations relating to the installed terminal. The values can be
changed at any time by the CICS_EpiSetSecurity function.
The client application can pass the userid and password to the
CICS_SetDefaultSecurity function. The values are server-specific and are
used whenever the terminal-specific values are not available. The values can
be changed at any time by the CICS_SetDefaultSecurity function.
If the userid and password are required for intersystem conversations and
have not been set by the CICS_EpiAddExTerminal or CICS_EpiSetSecurity
or CICS_SetDefaultSecurity functions then the CICS Transaction Gateway
may use other methods to determine the values.
For information on how to provide a userid and password, on UNIX or
Windows, see Client Security, inCICS Transaction Gateway: UNIX Administration
or CICS Transaction Gateway: Windows Administration.
Signon incapable terminals
The userid determined by the CICS Transaction Gateway is authenticated by
the server for each transaction started at a signon incapable terminal. The
transaction is executed in the server with the authorities assigned to the
authenticated userid.
If no userid is passed by the CICS Transaction Gateway, then the transaction
is executed in the server with the authorities assigned to the default userid.
Signon capable terminals
The userid, if any, determined by the CICS Transaction Gateway may be
authenticated by the CICS server for each transaction started at a signon
capable terminal. Such transactions are executed in the CICS server with the
authorities assigned to a userid determined by the client application or to the
default userid.
The first transaction(s) to be started at the terminal are executed with the
authorities assigned to the default userid.
Signon transactions are CICS-supplied or user-written. In both cases, the
userid and password are determined by the client application and are
28 CICS Transaction Gateway: Programming Guide

External Presentation Interface (EPI)
embedded in the 3270 data stream passed to the CICS_EpiStartTran or
CICS_EpiReply functions. If the userid is authenticated then subsequent
transactions started at the terminal are executed in the CICS server with the
authorities assigned to the authenticated userid.
The client application may start a signoff transaction at the terminal. The
userid may be signed off by the server following a predefined period of
inactivity. In either case, subsequent transactions started at the terminal are
executed with the authorities assigned to the default userid.
Note: A CICS server may reject an attempt to install a signon capable
terminal. This would be the case for CICS for OS/400 ® where all
authentication is managed by the operating system.
Security on z/OS Servers
Security checking done in the server for transactions started at a signon
capable terminal installed by a Client application does not depend on what is
specified by the ATTACHSEC option for the connection representing the
Client daemon. Instead security checking depends on whether the user signs
on while using the terminal.
If the user does not sign on, the Client daemon installed terminal is associated
with the default user defined for the server in the SIT. When a transaction is
run, the security checks are carried out against this default user. A check is
also done against the userid associated with the connection to see whether the
Client daemon itself has authority to access the resource.
When a user does sign on, the terminal is associated with the userid just
authenticated. For transactions attempting to access resources, security
checking is done against the userid associated with the connection and the
signed-on user’s userid.
It is recommended that the Usedfltuser parameter on the server connection
definition is set to Yes if using signon capable terminals and to No if using
signon incapable terminals.
EPI versions
The following descriptions of EPI functions embrace three versions of the EPI.
You should consult the documentation for your client or server environment
to determine which versions of the EPI they provide. You establish the version
of the EPI that you need by using the Version parameter on the
CICS_EpiInitialize function. This will return one of the following:
v CICS_EPI_VERSION_100
v CICS_EPI_VERSION_101
Chapter 3. External Presentation Interface (EPI) 29

EPI versions
v CICS_EPI_VERSION_200
The functions described in the following sections are the functions for
versions up to CICS_EPI_VERSION_200. The following functions and data
structures are only supported for CICS_EPI_VERSION_200:
v CICS_EpiAddExTerminal
v CICS_EpiPurgeTerminal
v CICS_EpiSetSecurity
v CICS_EpiAttributes_t
v The MapName, MapSetName,System, TermID, and SignonCapability
fields in the CICS_EpiDetails_t data structure
The following are not supported for CICS_EPI_VERSION_200:
v CICS_EpiGetSysError
v CICS_EpiSysError_t
In addition, if you initialize the EPI with CICS_EPI_VERSION_100, the
following restrictions apply:
v The CICS_EpiInquireSystem function is not supported.
v The return codes EPI_ERR_IN_CALLBACK, EPI_ERR_NULL_PARM, and
EPI_ERR_SECURITY are not supported. EPI_ERR_FAILED will be returned
instead.
v The System parameter of CICS_EpiAddTerminal must specify a non-null
string, as the mechanism for finding a default server is not supported. (If a
null string is specified, CICS_EPI_ERR_SYSTEM is returned.)
3270 data streams for the EPI
The data streams implemented for the EPI follow those defined in the 3270
Data Stream Programmer’s Reference. All data flows for the EPI are in ASCII
format, and structured fields are not supported. Data flows are defined under
the following topics in the 3270 Data Stream Programmer’s Reference:
v Introduction to the 3270 data stream (excluding structured fields)
v 3270 data stream commands
v Character sets, orders and attributes
v Keyboard and printer operations.
The use of 3270 data streams within the EPI, and some nonstandard orders
and attributes, are defined here.
The supplied C header file, cics3270.g, and the COBOL copybook cics3270.cbl,
contain constants and conversion tables that you will find useful in handling
3270 data streams.
30 CICS Transaction Gateway: Programming Guide

Note that if a CICS user transaction issues EXEC CICS SEND and EXEC CICS
RECEIVE commands, CICS does not process the data (after the initial control
bytes) that is passed between the EPI application and the CICS transaction. In
this case, the data buffer may be used to pass user-specified data between the
programs. Be aware that the contents of the data buffer may be code-page
converted if the buffer is passed between CICS systems, in which case the
data should be limited to ASCII and EBCDIC characters.
If a CICS transaction issues EXEC CICS SEND MAP and EXEC CICS
RECEIVE MAP commands, CICS converts the data from the BMS structure to
a 3270 data stream. In this case, the application receives 3270 data from CICS
and should return valid 3270 data to be converted for the transaction.
The distributed CICS products (that is, CICS Transaction Gateway and CICS
Universal Client) support the ASCII-7 subset of the 3270 data stream
architecture. This precludes the use of 14- and 16- bit addresses, or structured
fields, and means that only 12-bit SBA addressing is supported. Because of
this restriction, the maximum screen size for EPI terminals is 27 rows by 132
columns. The CICS/390 and CICS/400 ® products support the EBCDIC 3270
data stream architecture. However transactions on these servers must avoid
the use of 14- and 16- bit addresses and structured fields if these are to be
started from one of the distributed CICS products.
Inbound data streams (EPI to CICS)
AID
(1 byte)
Cursor address
(2 bytes)
Data buffer
(variable length)
3270 data streams
EPI applications send 3270 data to CICS on calls to the following functions:
v CICS_EpiStartTran
v CICS_EpiReply.
The format in both cases is the same. The data stream must be a minimum of
3 non-null bytes, representing the AID and cursor address; the sole exception
to this is if the AID represents the CLEAR key or a PA key, when the data
stream may consist of the AID only. These fields are passed to the CICS
transaction in the EIBAID and EIBCPOSN fields of the EIB.
The contents of the data buffer consist of:
v ASCII displayable characters with embedded 3270 control characters, when
it is passed to an EXEC CICS RECEIVE MAP command.
v User-specified data, when it is passed to an EXEC CICS RECEIVE
command.
Chapter 3. External Presentation Interface (EPI) 31

3270 data streams
On starting a transaction, the transaction ID is extracted from the start of the
data buffer as follows:
v If a set buffer address (SBA) order is present at the start of the data buffer,
the transaction ID is extracted from the 4th through 7th bytes of the buffer.
v If an SBA is not present at the start of the data buffer, the transaction ID is
extracted from the 1st through 4th bytes of the buffer.
In either case, the transaction ID may be shorter than 4 bytes, being delimited
by either another SBA, an ASCII space, or the end of the string.
The contents of the data buffer passed on the start of a CICS transaction are
available to the transaction in response to an initial EXEC CICS RECEIVE
command.
When the application replies, the contents of the data buffer are available in
an unconverted form in response to an EXEC CICS RECEIVE command or
converted to a BMS structure in response to an EXEC CICS RECEIVE MAP
command.
Note: It is the EPI programmer’s responsibility in the latter case to ensure that
the data is formatted correctly so that the conversion succeeds.
Outbound data streams (CICS to EPI)
Command
(1 byte)
Write control
character
(1 byte)
Data buffer
(variable length)
The 3270 commands are either write or read commands, instructing the EPI to
process the data or to reply with data respectively.
On a CICS_EPI_EVENT_SEND event, the command is one of the following
3270 write commands:
v Write
v Erase/Write
v Erase/Write Alternate
v Erase All Unprotected.
The first three commands are followed by a write control character (WCC)
and data. An Erase All Unprotected command has neither WCC nor data. The
Write Structured Field command is not generated by CICS and is therefore not
supported for the EPI.
The contents of the data buffer consist of:
32 CICS Transaction Gateway: Programming Guide

3270 data streams
v ASCII displayable characters with embedded 3270 control characters, when
it is passed from an EXEC CICS SEND MAP command.
v User-specified data, when it is passed from an EXEC CICS SEND
command.
A CICS_EPI_EVENT_CONVERSE event specifies a read command. The
contents of the data stream vary with the source of the event, as follows:
v If the event is the result of an EXEC CICS RECEIVE command, the data
buffer might contain data sent by the transaction, or it might be empty. The
EPI program should reply when the data to be sent is available.
v If the event is the result of an EXEC CICS RECEIVE BUFFER command, the
data buffer contains the 3270 Read Buffer command. This should be
processed as described in the 3270 Data Stream Programmer’s Reference.
3270 order codes
3270 orders are included in both inbound and outbound data streams to
provide additional control function. Table 3 lists the order codes that may
occur in 3270 data streams, and shows whether they relate to inbound or
outbound data streams, or both.
Table 3. Order codes occurring in 3270 data streams
Order code Inbound Outbound
Start field (SF) Yes Yes
Start field extended (SFE) Yes Yes
Set buffer address (SBA) Yes Yes
Set attribute (SA) Yes Yes
Modify field (MF) No Yes
Insert cursor (IC) No Yes
Program tab (TB) No Yes
Repeat to address (RA) No Yes
Erase unprotected to address (EUA) No Yes
Graphic escape (GE) No No
Note: The 3270 Data Stream Programmer’s Reference states that the SFE, SA, and
MF orders are not supported in ASCII. However, they do occur in 3270
data streams for the EPI, where they take the following values:
SFE X’10’
SA X’1F’
MF X’1A’
Chapter 3. External Presentation Interface (EPI) 33

3270 data streams
Each of these orders is followed by one or more attribute type-value
pairs. The count of attribute pairs and the attribute type are both binary
values, and are thus as defined in the 3270 Data Stream Programmer’s
Reference. However, the contents of the attribute value field may vary
from those defined in the 3270 Data Stream Programmer’s Reference as
follows:
v If the attribute type is less than or equal to X'C0' (for example, a
color), the attribute value is defined as an EBCDIC value in the 3270
Data Stream Programmer’s Reference. The EPI uses the ASCII
equivalent of the EBCDIC value; for example, red is defined as X'F2'
in the 3270 Data Stream Programmer’s Reference, and should be defined
as X'32' in the EPI data stream.
v If the attribute type is greater than X'C0' (for example, field
outlining), the attribute value is a binary value. The EPI uses the
values defined in the 3270 Data Stream Programmer’s Reference.
Further details of 3270 orders and other control characters are supplied in the
files named in the following table.
COBOL copybook
Supplied file
cics3270.cbl
C header file cics3270.h
34 CICS Transaction Gateway: Programming Guide

Chapter 4. External Security Interface (ESI)
Overview
This chapter describes the External Security Interface (ESI).
Although the interface is described in a way that is independent of
programming language, the names used for elements of the interface are
similar to those used in programming.
Information that is specific to programming languages is in the following
chapters:
v Chapter 5, “Programming in C and COBOL” on page 39
v Chapter 6, “Programming in C++” on page 45
v Chapter 7, “Programming in Java” on page 73
v Chapter 8, “Programming using J2EE” on page 115
v Chapter 9, “Programming in COM” on page 137
The Chapter is organized as follows:
“Overview”
“Benefits of APPC PEM” on page 36
“Benefits of ESI” on page 36
ESI allows a non-CICS application to invoke services provided by advanced
program-to-program communication (APPC) password expiration
management (PEM).
APPC PEM with CICS provides support for an APPC architected sign-on
transaction that signs on userids to a CICS server, and processes requests for a
password change by:
v Identifying a user and authenticating that user’s identification
v Notifying specific users during the authentication that their passwords have
expired
v Letting users change their passwords when (or before) the passwords expire
v Telling users how long their current passwords will remain valid
v Providing information about unauthorized attempts to access the server
using a particular user identifier
© Copyright IBM Corp. 2002 35

External Security Interface (ESI)
Benefits of APPC PEM
APPC PEM has the following benefits:
v It enables users to update passwords on APPC links.
This can be particularly useful in the case of expired passwords. On APPC
links that do not support APPC PEM, when users’ passwords expire on
remote systems, they are unable to update them from their own systems.
The only alternative on a non-APPC PEM system is to log on directly to the
remote system using a non-APPC link, such as an LU2 3270-emulation
session, to update the password.
v It provides users of SNA, or TCP62, with additional information regarding
their sign-on status, for example, the date and time at which they last
signed on. It informs users whether their userid is revoked, or the
password has expired, when they provide the correct password or
PassTicket.
Benefits of ESI
To use APPC PEM, you need a PEM client (requestor) and a PEM server
linked by a SNA, or TCP62, session. An external security manager (ESM),
such as resource access control facility (RACF ® ), or an equivalent ESM, must
also be available to the PEM server.
ESI provides the following functions:
v The CICS_VerifyPassword function, which allows a client application to
verify that a password matches the password recorded by an ESM for a
specified userid.
v The CICS_ChangePassword function, which allows a client application to
change the password recorded by an ESM for a specified userid.
v The CICS_SetDefaultSecurity function, which allows a client application to
specify a default userid and password to be used for ECI and EPI request
to the server.
These functions allow a non-CICS application program to act as a PEM
requestor without the application programmer having to manage an APPC
conversation, which implies knowledge of the formats for PEM requests and
replies, and of the interface to the local PEM server.
36 CICS Transaction Gateway: Programming Guide

Part 2. Language Specific information
© Copyright IBM Corp. 2002 37

38 CICS Transaction Gateway: Programming Guide

Chapter 5. Programming in C and COBOL
This Chapter contains information about the external access interfaces, that is
specific to C and Cobolt, and is organized as follows:
“Supported operating systems”
“Writing the non-CICS applications”
“Making ECI calls” on page 40
“Making EPI calls” on page 42
“Compiling and linking applications” on page 42
This chapter does not deal with testing or debugging ECI and EPI
applications. You should refer to the programming documentation for the
environment in which you are working.
Supported operating systems
v Programming applications in C for the CICS Transaction Gateway is
supported on the AIX ® , HP-UX, Linux, Solaris and Windows operating
systems.
v Programming applications in COBOL for the CICS Transaction Gateway is
supported only on the Windows operating system.
Writing the non-CICS applications
ECI and EPI applications are stand-alone programs that can be run on any
programs that can be run on any of the CICS Universal Client or CICS
Transaction Gateway systems except CICS Transaction Gateway for z/OS.
Programs that do not make operating-system-specific calls are portable
between these environments. The sample programs and associated build files for
your environment illustrate much of what is discussed here.
An application program may use the facilities of both ECI and EPI.
An application must be constructed as a single process, though in
environments in which a process can generate several threads, an application
can be multi-threaded.
This chapter explains the writing of programs in the C and Cobol
programming languages.
© Copyright IBM Corp. 2002 39

Creating applications
The following table shows the header files for C required in your programs:
Use File
ECI cics_eci.h
EPI cics_epi.h
Type definitions cicstype.h
The following table shows the copybook files for COBOL required in your
programs:
Use File
ECI cicseci.cbl
EPI cicsepi.cbl
Note: Cobol is only supported on the Windows operating system.
You should study the contents of the files you intend to use. Each file contains
the definitions of all the entry points, types, data structures, and constants
needed for writing programs for the corresponding interface.
When compiling C programs, you may need to ensure that the structures
passed to the CICS external facilities are packed. If this is necessary, the C
header files will contain the #pragma pack directive, which should not be
changed.
Making ECI calls
ECI functions are called in the manner described below.
COBOL applications must ensure that the ECI function calls are statically
linked at link time by using the system linkage convention.
For Micro Focus Object COBOL, you should use call-convention 8 for every
program call, or use the default call-convention 0 and compile using the
LITLINK compiler directive.
CICS_ExternalCall
The method of calling CICS_ExternalCall is shown here for C and COBOL.
The ECI parameter block (ECI_PARMS for C and ECI-PARMS for COBOL) is
used for passing parameters to the ECI. The format of the call and associated
declarations is as follows:
For C programs:
40 CICS Transaction Gateway: Programming Guide

ECI_PARMS EciBlock;
cics_sshort_t Response;
.
.
.
Response = CICS_ExternalCall(&EciBlock);
For COBOL programs:
CALL CICSEXTERNALCALL
USING BY REFERENCE ECI-PARMS
RETURNING ECI_ERROR_ID.
The name _CICS_ExternalCall may also be used with the Micro Focus Object
COBOL compiler, but it is not recommended.
Callback routines
Each callback routine has only one parameter. You should consult the sample
programs for examples of writing callback routines.
Callback routines can be used in C but are not available in Cobol.
CICS_EciListSystems
The format of the CICS_EciListSystems call for C is as follows:
#define MAX_SYS 5
cics_sshort_t Response;
cics_ushort_t Count;
CICS_EciSystem_t List[MAX_SYS];
.
Count = MAX_SYS;
.
Response = CICS_EciListSystems(NULL, &Count, List);
Creating applications
The COBOL name of the system information structure is CICS-ECISYSTEM
The format of the CICS_EciListSystems call for COBOL is as follows:
01 LIST-SIZE PIC 9(4) COMP-5.
CALL CICSECILISTSYSTEMS
USING
BY REFERENCE NULL-PTR
BY REFERENCE LIST-SIZE
BY REFERENCE CICS-ECISYSTEM
RETURNING ECI-ERROR_ID.
The name _CICS_EciListSystems may also be used with the Micro Focus Object
COBOL compiler, but it is not recommended.
Chapter 5. Programming in C and COBOL 41

Creating applications
Making EPI calls
EPI functions
EPI functions are called in a standard manner. an example of calling the
CICS_EpiListSystems function for C and COBOL follow:
For C programs:
#define MAX_SYS 5
CICS_EpiSystem_t System;
cics_ushort-t Count;
cics_sshort_t Response;
.
Count = MAX_SYS;
.
Response = CICS_EpiListSystems(NULL, &Count, &System);
For Cobol programs:
01 COUNT PIC 9(4) COMP-5.
01 NAMESPACE POINTER.
.
.
.
CALL CICSEPILISTSYSTEMS
USING BY VALUE NAMESPACE
BY REFERENCE COUNT
BY REFERENCE CICS-EPISYSTEM
RETURNING EPI-RETURN-CODE.
Callback routines
Each callback routine has only one parameter. You should consult the sample
programs for examples of writing callback routines.
Callback routines can be used in C but are not available in Cobol.
Compiling and linking applications
This section gives some examples showing how to compile and link typical
ECI and EPI applications in the various client environments. These are
examples only, and may refer to specific compilers and linkers.
Refer to the samples supplied with your environment (see Appendix B,
“Sample Programs” on page 167) for more information about compiling and
linking programs.
For details of supported compilers, see the CICS Transaction Gateway:
Administration book for your operating system.
42 CICS Transaction Gateway: Programming Guide

Client daemon for Windows
For C Programs:
cl /c /DWIN32 /D_WIN32 /D_X86_=1 /DCICS_W32 program.c
link program.obj cclwin32.lib
Figure 7. Command to issue for C compiling
Notes:
v The compiler options /DWIN32, /D_WIN32, and /D_X86_=1 are used to
select the correct Windows function and are standard Win32 options. These
options are not specific to the CICS Transaction Gateway.
v The compiler option /DCICS_W32 must be used to define the symbol
CICS_W32 to the compiler to ensure that the CICS header files are
processed correctly.
v The application must be linked with the CCLWIN32.LIB library in addition
to the standard C runtime and Windows libraries.
v Callback functions must be declared using the CICSEXIT calling
convention—see samples for details.
For COBOL Programs:
cobol program;
cblnames -mPROGRAM program.obj
link ecicobnl.obj cbllds.obj /NOD cclwin32.lib mfrts32.lib msvcrt.lib kernel32.lib
Figure 8. Command to issue for COBOL compiling
Notes:
1. ″program″ must be replaced by the name of the program, and
″PROGRAM″ must be replaced by the name of the program in upper case
2. It is important to use the correct calling convention when invoking the ECI
or EPI from COBOL. The sample programs use the ″SPECIAL-NAMES.
CALL CONVENTION 8 IS CICS.″ statements to achieve this
3. The application must be linked with the CCLWIN32.LIB library, in
addition to the standard COBOL libraries, because a 32-bit Windows
application is being generated.
4. ECI or EPI callback functions are not supported in COBOL applications.
Client daemon for AIX
cc_r -c -DCICS_AIX -I/include program.c
cc_r -o program program.o -lpthreads -lc_r -lcclaix
Creating applications
Chapter 5. Programming in C and COBOL 43

Creating applications
Notes:
v The constant CICS_AIX must be defined to the compiler using the
-DCICS_AIX option.
v The application must be linked with the standard AIX libpthreads.a and
libc_r.a libraries, as well as the libcclaix.a library.
Client daemon for Solaris
cc -c -DCICS_SOL -I/include program.c
cc -o program program.o -lpthread -lc -lcclsol
Notes:
v The constant CICS_SOL must be defined to the compiler using the
-DCICS_SOL option.
v The application must be linked with the standard Solaris libpthread.so and
libc.so libraries, as well as the libcclsol.so library.
44 CICS Transaction Gateway: Programming Guide

Chapter 6. Programming in C++
Establishing the working environment
You are provided with C++ (OO) support for CICS Transaction Gateway on
AIX, HP-UX, Linux, Solaris and Windows operating systems. This includes
the class library, C++ header files, the BMS map utility, and sample code.
See Supported software in the CICS Transaction Gateway: Administration book for
your operating system, for full details of CICS server platforms supported by
the CICS Transaction Gateways.
Windows environment variables
On the Windows operating system there are system specific (these apply to all
users) and user specific environment variables. This is illustrated by the
screenshot in Figure 9 on page 46 where the top pane is the user environment
variables and the bottom one is the generic system ones. This duplication can
cause problems due to the user variables taking precedence over the system
ones.
© Copyright IBM Corp. 2002 45

Establishing the working environment
Figure 9. Duplication of environment variables on the Windows Operating System
CICS Transaction Gateway and CICS Universal Client append directories to
the LIB and INCLUDE variables only in the system set, to ensure that these are
used you should add ;%LIB% to the end of your user LIB environment variable
and ;%INCLUDE% to the end of your user INCLUDE environment variable. The
CICS Transaction Gateway appends ;%CLASSPATH% to your user CLASSPATH
environment variable. When you select OK on the Edit user variable window
to make this change, the variable is displayed with the system paths
appended.
46 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
Compiling and Linking
Refer to the sample programs for more information about compiling and
linking programs; see Appendix B, “Sample Programs” on page 167.
Your C++ program source needs #include statements to include either
cicseci.hpp, for the ECI classes, or cicsepi.hpp, for the EPI classes. These
files are in the \include subdirectory.
On UNIX operating systems, when compiling C++ applications that use the
CICS C++ libraries, define these macros instead of CC_UNIX:
Operating system Macro
AIX CICS_AIX
HP-UX CICS_HPUX
Linux CICS_LNX
Solaris CICS_SOL
Compiling and Linking
Multi-Threading
The CICS Transaction Gateway C++ libraries are not completely thread-safe.
That is, they do not have critical sections, or semaphores, to prevent two
threads from updating the same instance of an object. However, the classes do
not share data, so they can be used in a well designed, multi-threaded,
program. The normal technique is for each thread to have its own instance of
lightweight objects, such as CclConn, CclFlow, CclBuf.
Handling Exceptions
Most class methods could generate an exception. The default exception
handler is found in the handleException method in the CclECI and CclEPI
classes. It is a simple routine which does a C++ throw of a CclException
object. It does not perform any action if an exception occurs within the
destruction of an object. You must not do a throw within a destructor as this
causes unpredictable results.
This routine is suitable for most needs when using synchronisation modes of
dsync and sync. For example:
Chapter 6. Programming in C++ 47

Handling Exceptions
#include
#include
void main(void) {
CclECI *eci;
eci = CclECI::instance();
CclFlow flow(Ccl::sync);
CclBuf buf;
CclConn conn("CICSOS2","SYSAD","SYSAD");
buf.setDataLength(80);
try {
conn.link(flow,"EC01",&buf);
cout

Once you have subclassed the ECI Class, you still can only create one object
of this class for your application, however do not use the instance method,
you must create the object either explicitly e.g.
MyCclECI myeci;
or by using the new operator
MyCclECI *pmyeci;
pmyeci = new MyCclECI;
Handling Exceptions
External call interface
The ECI is one of two interfaces through which a non-CICS client program
can interact with a CICS server. The ECI object model consists of a set of
classes which give access to the features of the ECI and supports an
object-oriented approach to CICS Transaction Gateway programming with the
ECI. The following classes are included:
Table 4. C++ ECI classes.
Object Classname Description
Global Ccl Contains global enumerations
Buffer CclBuf Used for exchanging data with a server
Connection CclConn Models the connection to a server
ECI CclECI Controls and lists access to CICS servers
Exception CclException Encapsulates exception information
Flow CclFlow Handles a single client/server interaction
SecAttr CclSecAttr Provides information about security
attributes (passwords)
SecTime CclSecTime Provides date and time information
UOW CclUOW Corresponds with a Unit of Work in the
server—used for managing updates to
recoverable resources.
Using COMMAREAs
A COMMAREA is a block of storage allocated by the program. The client
program uses the COMMAREA to send data to the server and the server uses
the same storage to return data to the client. Therefore, you must create a
COMMAREA that is large enough to contain all the information to be sent to
the server and large enough to contain all the information that can be
returned from the server.
Chapter 6. Programming in C++ 49

External call interface
For example, you need to send a 12 byte serial number to the server, but you
may receive 20 Kb back from the server. You must create a COMMAREA of
size 20 Kb. Your code would look like this:
// serialNo is a Null terminated string
CclBuf Commarea; // create extensible buffer object
Commarea.assign(strlen(serialNo),serialNo); // Won’t include the Null
Commarea.setDataLength(20480); // stores Nulls in the unused area
In the example, the serial number is stored in the new Commarea which is then
increased in size to 20480. The extra bytes are filled with nulls. This is
important as it ensures that the information transmitted to the server is kept
to a minimum. The CICS Transaction Gateway software strips off the excess
nulls and transmits 12 bytes to the server.
Finding potential servers
Information about the CICS servers that can be used by a client program is
defined in the CICS Transaction Gateway configuration file. See Configuration
in the CICS Transaction Gateway: Administration book for your operating
system, for more information. The existence of such a definition doesn’t
guarantee availability of a server.
The ECI object CclECI provides access to this server information through its
serverCount, serverDesc, and serverName methods.
Unless the ECI class has been subclassed, its unique instance is found using
the class method instance as in the following example:
CclECI* pECI = CclECI::instance();
printf( "Server Count = %d\n", pECI-> serverCount() );
printf( "Server1 Name = %s\n", pECI-> serverName( 1 ) );
...
Typical output produced:
Server Count = 2
Server1 Name = DEVTSERV
Server connection
A client program requires one connection object, CclConn, for each CICS
server with which it will interact. When a connection object is created,
optional data can be specified which includes:
v The name of the server to be connected. This must be one of the server
names defined in the CICS Transaction Gateway configuration file. If this
name is omitted, the default server will be used.
v A user ID. Some servers might require that a client application provides a
user ID and password before they permit specific interactions.
50 CICS Transaction Gateway: Programming Guide

v A password.
In this example, a connection object is created with a server name, user ID
and password:
CclConn serv2( "Server2","sysad","sysad" );
External call interface
Creating a connection object does not, in itself, cause any interaction with the
server. The information in the connection object is used when one of the
following server request calls is issued:
link—to request the execution of a server program.
status—to request the status (availability) of the server.
changed—to request the notification of any change in this status.
cancel—to request the cancellation of a changed request.
These are methods of the connection class. There are two other server request
calls; the backout and commit methods of the unit of work class. More
information on the use of all these methods can be found in following
sections.
Monitoring server availability
The connection object CclConn has three methods which can be used to
determine the availability of the server connection that it represents:
status requests the status (that is, the availability) of the server.
changed
requests notification of any change in this status.
cancel
requests cancellation of a changed request.
The example described below shows how server availability can be monitored
in a client program that is busy doing something else.
Here is a subclass of the flow class designed for use with server status calls.
The reply handler implementation prints the server name and its
newly-changed status; it ignores the returned communication area. Next, it
issues a changed server request so that the next server status change will be
received. The reply handler will be called every time the availability of the
server changes.
Chapter 6. Programming in C++ 51

External call interface
class ChgFlow : public CclFlow {
public:
ChgFlow( Ccl::Sync stype ) : CclFlow( stype ) {}
void handleReply( CclBuf* ) {
CclConn* ccon = connection();
cout serverName()

In the next example, an existing memory structure is used. This could, for
example, correspond to a record used in the server program. In this case, the
buffer object knows the record is fixed-length, externally-defined, and ensures
it can not be extended in any subsequent processing. The link call requests
execution of the program QVALUE on the CICS server defined by the serv2
connection object and passes data via the structure on which the buffer object
comma2 is overlaid.
struct rec{
short key;
char name[8];
char retval[70];
};
rec record1 = { 1234,"Hilary" };
CclBuf comma2( sizeof(rec),&record1 );
serv2.link( sflow,"QVALUE",&comma2 );
...
The communications area returned from a server is also contained in a buffer
object.
Controlling server interactions
A flow object—CclFlow—controls each interaction between the client program
and a server and determines the synchronization of reply processing;
synchronous, deferred synchronous or asynchronous. This example creates a
synchronous flow object:
CclFlow sflow( Ccl::sync );
External call interface
A flow object is referenced when a server request call is first issued and
remains active from that time until all client processing of the corresponding
reply from the server has been completed. At that point it is set inactive and
becomes available for reuse or deletion. During its active lifespan, a flow
object maintains the state of the client/server interaction it is controlling.
The flow class should be subclassed to provide the implementation of a reply
handler which will be called when a reply is received; this happens regardless
of the synchronization type. The reply handler is passed a buffer object which
contains the communication area returned by the server. A default reply
handler is provided; it just returns to the caller without doing anything.
Separate flow subclasses could be needed to cater for different client/server
communication area protocols. Many flows may be active at the same time.
Many servers may be used simultaneously by the same CICS Transaction
Gateway or CICS Universal Client.
Chapter 6. Programming in C++ 53

External call interface
Synchronous reply handling
In the synchronous model, the client remains blocked at the server request call
until a reply is eventually received from the server.
The example program in Figure 10 calls a server program using parameters
supplied on the command line. It does no subclassing to handle exceptions or
to handle the reply from the server.
...
CclECI* pECI = CclECI::instance();
CclConn server1( argv[1],argv[2],argv[3] );
CclBuf comma1( argv[4] );
CclFlow sflow( Ccl::sync );
server1.link( sflow,"ECIWTO",&comma1 );
Figure 10.
The program gains access to the ECI object and constructs a connection object
using the supplied server name, password and user ID. Then a buffer object is
constructed using text from the command line and a synchronous flow object
is created.
The link call requests execution of the CICS ECIWTO sample program on the
server and passes text to it in the buffer. Processing is then blocked until a
reply is received from the server. ECIWTO just writes the communication area
to the operator console on the server and returns it, unchanged, to the client.
After the reply is received, the program reports the most recent exception
code and prints the returned communication area:
cout

Asynchronous reply handling
In the asynchronous model, the client program issues a server request call and
then continues immediately with the next statement without waiting for a
reply. As soon as the reply is received from the server it is immediately
passed to the reply handler of the flow object controlling the interaction; in
parallel with whatever else the client happens to be doing.
The example program in Figure 11 calls a server program using parameters
supplied on the command line. It subclasses the ECI class to handle
exceptions and subclasses the flow class to handle the reply from the server.
Here is a simple subclass of the flow class with a reply handler
implementation which just prints the reply received:
class MyCclFlow : public CclFlow {
public:
MyCclFlow( Ccl::Sync sync ) : CclFlow( sync ) {}
void handleReply( CclBuf* pcomm ){
cout

External call interface
Meanwhile, when the reply does come back from the server, the reply handler
is called and, assuming there are no exceptions, prints the returned
communication area. Note that in the asynchronous model, the buffer object
to hold the returned communication area is allocated internally within the
flow object, and is deleted after the reply handler has run. The buffer object
supplied on the original link call is not used for the reply, and can be deleted
as soon as the link call returns.
If you call the program in Figure 11 on page 55 like this:
ecicpo2 DEVTSERV sysad sysad "Hello World"
the following output is expected on successful completion:
Server call in progress. Enter q to quit...
Reply from CICS server: Hello World
q
If the client program decides at some point that it really can do no more until
a reply is received from the server, it can use the wait method on the
appropriate flow object. This effectively makes the interaction synchronous,
blocking the client:
asflow.wait();
Deferred synchronous reply handling
In the deferred synchronous model, the client program issues a server request
call and then continues immediately with the next statement without waiting
for a reply. Unlike the asynchronous case, where a server reply is handled
immediately it arrives, the client decides when it wants to poll for a reply.
When a poll is issued, the flow object checks whether there is, in fact, a reply
from the original server request. If there is, the flow object’s reply handler is
called synchronously and is passed the returned communication area in a
buffer object. Poll returns a value to its caller indicating whether the reply
was received or not; if not it can try again later.
The same simple subclass of the flow class described above is used. There are
some small changes to the main program to indicate deferred synchronous
reply handling:
...
MyCclECI myeci;
CclConn server1( argv[1],argv[2],argv[3] );
CclBuf comma1( argv[4] );
MyCclFlow dsflow( Ccl::dsync );
server1.link( dsflow,"ECIWTO",&comma1 );
...
56 CICS Transaction Gateway: Programming Guide

For demonstration purposes, the program is now made to loop with a delay
until poll indicates the reply has been received from the server. Note that in
the deferred synchronous model, a buffer object to hold the returned
communication area can be supplied as a parameter to the poll method. If, as
in the example below, no buffer object is supplied on the poll method, one is
allocated internally within the flow object, and is deleted after the reply
handler has run.
...
Ccl::Bool reply = Ccl::no;
while ( reply == Ccl::no ) {
cout

External call interface
of work have successfully completed, the unit of work can be committed by
the commit method of the unit of work object or backed out by backout:
serv1.link( sflow, "ECITSQ", &( comma1="1st link in UOW" ), &uow );
serv1.link( sflow, "ECITSQ", &( comma1="2nd link in UOW" ), &uow );
...
uow.backout( sflow );
If no UOW object is used, each link call becomes a complete unit of work
(equivalent to LINK SYNCONRETURN in the CICS server).
Whenever using logical units of work, you must ensure that you backout or
commit active units of work, especially at program termination. You can check
to see if a logical unit of work is still active by checking the uowId method of
the CclUOW class for a non zero value.
Security Management for ECI
You can perform security management on servers that support Password
Expiry Management (PEM). See Supported software in the CICS Transaction
Gateway: Administration book for your operating system, for more information
on supported servers and protocols.
To use these features you first must have constructed a Connection object. The
two methods available are verifyPassword which checks the userid and
password within the connection object with the Server Security System, and
changePassword which allows you to change the password at the server. If
successful the connection object password is updated accordingly.
If either call is successful, you are returned a pointer to an internal object
which provides information about the security, a CclSecAttr object. This object
provides access to information such as last verified Date and Time, Expiry
Date and Time and Last access Date and Time. If you query for example last
verified Date, you get back a pointer to an object which allows you to get the
information in various formats. The following is a sample of code to show the
use of these various objects:
58 CICS Transaction Gateway: Programming Guide

Connection object already created called conn
CclSecAttr *pAttrblock; // pointer to security attributes
CclSecTime *pDTinfo; // pointer to Date/Time information
try {
pAttrblock = conn->verifyPassword();
pDTinfo = pAttrblock->lastVerifiedTime();
cout

|
|
C++ External presentation interface
1. General purpose C++ classes for handling 3270 datastream, such as fields
and attributes, and CICS transaction routing data, such as transaction ID.
2. Generation of C++ classes for specific CICS applications from BMS map
source files. These classes allow client applications to access data on 3270
panels, using the same field names as used in the CICS server BMS
application.
Note: These classes do not contain any specific support for 3270 datastreams
that contain DBCS fields. However they do not support 3270
datastreams that contain mixed SBCS and DBCS fields.
The BMS utility is a tool for statically producing C++ class source code
definitions and implementations from a CICS BMS mapset.
The following table describes the supplied classes. For full details of the
methods each class provides, refer to the C++ chapter, in CICS Transaction
Gateway: Programming Reference.
Table 5. C++ EPI classes.
Object Classname Description
Global Ccl Contains global enumerations.
EPI CclEPI Initializes the EPI. This class also has
methods that obtain information on CICS
servers accessible to the CICS Transaction
Gateway.
Exception CclException Encapsulates error information.
Field CclField Supports a single field on a virtual screen
and provides access to field text and
attributes.
Map CclMap This class provides access to CclField
objects, using BMS map information. The
CICSBMSC utility generates classes derived
from CclMap.
Screen CclScreen
See note on page 61 for BMS support on
Linux.
Each terminal (CclTerminal object) has a
virtual screen associated with it. The
CclScreen class contains a collection of
CclField objects and methods to access these
objects. It also has methods for general
screen handling.
SecAttr CclSecAttr Provides information about security
attributes (passwords)
60 CICS Transaction Gateway: Programming Guide

|
|
C++ External presentation interface
Table 5. C++ EPI classes. (continued)
Object Classname Description
SecTime CclSecTime Provides date and time information
Session CclSession Controls communication with the server in
synchronous, asynchronous and deferred
synchronous modes.
Terminal CclTerminal
Applications can use CclSession to derive
their own classes to encapsulate specific
CICS transactions.
Controls a 3270 terminal connection to CICS.
The CclTerminal class handles CICS
conversational, pseudo-conversational, and
ATI transactions. One application can create
many CclTerminal objects.
Linux
Note: CICSBMSC is not provided with CICS Transaction Gateway for the
Linux operating system.
End of Linux
Support for Automatic Transaction Initiation (ATI)
The CICS server API call EXEC CICS START allows a server program to start
a transaction on a particular terminal. This mechanism, called Automatic
Transaction Initiation (ATI), requires additional programming at the client side
to handle the interaction between these transactions and normal
client-initiated transactions.
Firstly, client applications can control whether ATI transactions are allowed by
using the setATI() and queryATI() methods on the CclTerminal class.The
default setting is for ATIs to be disabled. The following code fragment shows
how to enabled ATIs for a particular terminal:
// Create terminal connection to CICS server
CclTerminal terminal( "myserver" );
// Enable ATIs
terminal.setATI(CclTerminal::enabled);
The CICS Transaction Gateway queues ATIs for a terminal while a transaction
is in progress. The CclTerminal class will perform one of more of the
following
v run any outstanding ATIs as soon as a transaction ends
v call Additional programming needed to handle the ATI replies
Chapter 6. Programming in C++ 61

C++ External presentation interface
v run ATIs before or between client-initiated transactions
depending on whether the call synchronisation type is Synchronous,
Asynchronous or Deferred synchronous.
Synchronous When you call the CclTerminal send() method, any
outstanding ATIs will be run after the client-initiated
transaction has completed. The CclTerminal class will wait for
the ATI replies then update the CclScreen contents as part of
the synchronous send() call. If you expect an ATI to occur
before or between client-initiated transactions, you can call the
CclTerminal receiveATI() method to wait synchronously for
the ATI.
Asynchronous When the client application calls the CclTerminal send()
method for an async session, the CclTerminal class starts a
separate thread to handle replies. If ATIs are disabled, this
thread finishes when the CICS transaction is complete. If ATIs
are enabled, the reply thread continues to run between
transactions. When the CclTerminal state becomes idle, any
outstanding ATIs are run and ATIs received subsequently are
run immediately. The reply thread is not started until the first
CclTerminal::send() call, so if you expect ATIs to occur
before any client-initiated transactions, you can call the
receiveATI() method to start the reply thread.
Deferred synchronous
After the CclTerminal send() method is called for a dsync
session, the poll() method is used to receive the replies.
Outstanding ATIs are started when the last reply has been
received (i.e. on the final poll() call). You can also call the
poll() method to start and receive replies for ATIs between
client-initiated transactions. As the poll() method can be called
before or between client-initiated transactions, the receiveATI()
method is not needed (and is invalid) for deferred
synchronous sessions. For any of the synchronisation types
you can provide a handleReply() method by subclassing the
CclSession class. As for client-initiated transactions, this
method will be called when the ATI 3270 data has been
received and the CclScreen object updated. The transID()
method on the CclTerminal or CclSession can be called to
identify the ATI.
Starting a 3270 terminal connection to CICS
The CICS Transaction Gateway EPI must be initialized, by creating a CclEPI
object, before a terminal connection can be made to CICS. The CclEPI object,
like the CclECI object, also provides access to information about CICS servers
62 CICS Transaction Gateway: Programming Guide

C++ External presentation interface
which have been configured in the CICS Transaction Gateway configuration
file. The following C++ sample shows the use of the CclEPI object:
#include // CICS Transaction Gateway EPI headers
...
CclEPI epi; // Initialize CICS Transaction Gateway EPI
// List all CICS servers in Gateway initialization file
for ( int i=1; i

C++ External presentation interface
// Get access to the CclScreen object
CclScreen* screen = terminal.screen();
for ( int i=1; i ≤ screen->fieldCount(); i++ ) {
CclField* field = screen->field(i); // get field by index
if ( field->textLength > 0 )
cout field(i); // get field by index
// Find unprotected (i.e. input) fields
if ( field->inputProt() == CclField::unprotect )
...
// Find fields containing a specific text string
if ( strstr(field->text(), "CICS Sign-on") )
...
// Find red fields
if ( field->foregroundColor() == CclField::red )
...
}
Note that the string “Sign-on” in the above sample may need to be changed
to meet local conventions. For example, an AIX server may use the string
“SIGNON”.
EPI call synchronization types
The CICS Transaction Gateway EPI C++ classes support synchronous
(“blocking”), and deferred synchronous (“polling”) and asynchronous
(“callback”) protocols.
In the example above the CclSession object is created with the synchronization
type of Ccl::sync. When this CclSession object is passed as the first parameter
on a CclTerminal send method, a synchronous call is made to CICS. The C++
program is then blocked until the reply was received from CICS. When the
reply is received, updates are made to the CclScreen object according to the
3270 datastream received, then control is returned to the C++ program.
To make asynchronous calls the CclSession object used on the CclTerminal
send method is created with a synchronization type of Ccl::async. The call is
made to CICS using the CclTerminal send method, but control returns
immediately to the client application without waiting for a reply from CICS.
64 CICS Transaction Gateway: Programming Guide

C++ External presentation interface
The CclTerminal object starts a separate thread which waits for the reply from
CICS. When a reply is received, the handleReply method on the CclSession
object is invoked. To process the reply, the handleReply method should be
overridden in a CclSession subclass:
class MySession : public CclSession {
public:
MySession(Ccl::Sync protocol) : CclSession( protocol ) {}
// Override reply handler method
void handleReply( State state, CclScreen* screen );
};
The implementation of the handleReply method can process the screen data
available in the CclScreen object, which will have been updated in line with
the 3270 datastream sent from CICS:
void MySession::handleReply( State state, CclScreen* screen ) {
// Check the state of the session
switch( state ) {
case CclSession::client:
case CclSession::idle:
// Output data from the screen
for ( int i=1; i < screen->fieldCount(); i++ ) {
cout

C++ External presentation interface
Most client applications will want to wait until the CICS server program has
finished sending data (that is, the CclSession/CclTerminal state is client or
idle) before processing the screen. However, some long-running server
programs may send intermediate results or progress information that can
usefully be accessed while the state is still server.
The implementation of the handleReply method can read and process data
from the CclScreen object, update fields as required, and set the cursor
position and AID key in preparation for the return transmission to CICS. The
application main program should invoke further methods (send or
disconnect) ontheCclTerminal object to drive the server application:
try {
// Connect to CICS server
CclTerminal terminal( "CICS1234" );
// Create asynchronous session
MySession session(Ccl::async);
// Start CESN transaction on CICS server
terminal.send( &session, "CESN" );
// Replies processed asynchronously in overridden
// handleReply method
...
} catch ( CclException &exception ) {
cout

C++ External presentation interface
try {
// Connect to CICS server
CclTerminal terminal( "CICS1234" );
// Create deferred synchronous session
MySession session(Ccl::dsync);
// Start CESN transaction on CICS server
terminal.send( &session, "CESN" );
...
if ( terminal.poll())
// reply processed in handleReply method
else
// no reply received yet
} catch ( CclException &exception ) {
cout

|
|
C++ External presentation interface
Client Application BMS Mapsets
CICS Map Classes
CICS EPI Classes
CICS Transaction Gateway
Figure 12. Use of BMS map classes
BMS Conversion Utility
The utility generates C++ class definitions and implementations that
applications can use to access the map data as named fields within a map
object. A class is defined for each map, allowing field names and lengths to be
known at compile time. The C++ classes use the CICS EPI base classes to
handle the inbound and outbound 3270 datastreams. The generated classes
inherit a base class CclMap that provides general functions required by all
map classes.
Run the CICSBMSC utility on the BMS source as follows:
CICSBMSC .BMS
Linux
See note on page 61 for BMS support on Linux.
End of Linux
Server BMS Application
CICS Server
The utility generates .HPP and .CPP files containing the definition and
implementation of the map classes.
68 CICS Transaction Gateway: Programming Guide

Having used the EPI BMS utility to generate the map class, use the base EPI
classes to reach the required 3270 screens in the usual way. Then use the map
classes to access fields by their names in the BMS map. The map classes are
validated against the data in the current CclScreen object.
Mapset containing a single map
The mapset listed in Figure 13 contains a simple map, MAPINQ1.
***************************************************************
* cicssda MAPINQ1 -- Wed 2 Aug 14:14:02 1995
***************************************************************
MAPINQ1 DFHMSD TYPE=&SYSPARM,MODE=INOUT,LANG=C,STORAGE=AUTO,TIOAPFX=YES
MAPINQ1 DFHMDI SIZE=(24,80),MAPATTS=(COLOR,HILIGHT,VALIDN),LINE=1, X
COLUMN=1,COLOR=NEUTRAL,HILIGHT=OFF
DTITLE DFHMDF POS=(2,2),LENGTH=5,ATTRB=(PROT,NORM),COLOR=TURQUOISE, X
CASE=MIXED,INITIAL=’Date:’
DATE DFHMDF POS=(2,9),LENGTH=8,ATTRB=(PROT,BRT),CASE=MIXED
...
PRODNAM DFHMDF POS=(5,24),LENGTH=40,ATTRB=(PROT,BRT),CASE=MIXED
...
APPLID DFHMDF POS=(15,15),LENGTH=8,ATTRB=(PROT,BRT),CASE=MIXED
...
MAPINQ1 DFHMSD TYPE=FINAL
Figure 13. Sample Map Class—BMS Source
C++ External presentation interface
The BMS Conversion Utility generates the C++ class definition (shown in
Figure 14 on page 70) from this mapset. The class name “MAPINQ1Map” is
derived from the map name in the BMS source. The class inherits the CclMap
class.
The class provides these main operations:
1. The constructor MAPINQ1Map invokes the parent constructor, that
validates the map object against the current screen.
2. The method field provides access to fields in the map, using the BMS
source field names (provided as an enumeration within the class).
Chapter 6. Programming in C++ 69

C++ External presentation interface
//************* CICS Transaction Gateway Classes *************************************
//
// FILE NAME: epiinq.hpp
//
// DESCRIPTION: C++ header for epiinq.bms
// Generated by CICS BMS Conversion Utility - Version 1.0
//
//***********************************************************************
#include // CICS Transaction Gateway EPI classes
//-----------------------------------------------------------------------
// MAPINQ1Map class declaration
//----------------------------------------------------------------------class
MAPINQ1Map : public CclMap {
public:
enum FieldName {
DTITLE,
DATE,
...
PRODNAM,
...
APPLID,
...
};
//-------------- Constructors/Destructors -------------------------------
MAPINQ1Map( CclScreen* screen );
~MAPINQ1Map();
//-------------- Actions ------------------------------------------------
CclField* field( FieldName name ); // access field by name
...
}; // end class
Figure 14. Sample Map Class—Generated C++ Header
Using EPI BMS Map Classes
The map classes generated using CICSBMSC can be compiled and built into a
client application. Note that when building Windows applications using
pre-compiled headers, add #include stdafx.h to the .cpp file generated by
CICSBMSC.
CclEPI, CclTerminal and CclSession objects are used in the normal way to
start a CICS transaction:
70 CICS Transaction Gateway: Programming Guide

try {
// Initialize CICS Transaction Gateway EPI
CclEPI epi;
// Connect to CICS server
CclTerminal terminal( "CICS1234" );
// Start transaction on CICS server
CclSession session( Ccl::sync );
terminal.send( &session, "EPIC" );
C++ External presentation interface
In this example the server program uses a BMS map for its first panel, for
which a map class “MAPINQ1Map” has been generated. When the map
object is created, the constructor validates the screen contents with the fields
defined in the map. If validation is successful, fields can then be accessed
using their BMS field names instead of by index or position from the
CclScreen object:
MAPINQ1Map map( terminal.screen() );
CclField* field;
// Output text from "PRODNAM" field
field = map.field(MAPINQ1Map::PRODNAM);
cout

C++ External presentation interface
If either call is successful, you are returned a pointer to an internal object
which provides information about the security, a CclSecAttr object. This object
provides access to information such as last verified Date and Time, Expiry
Date and Time and Last access Date and Time. If you query for example last
verified Date, you get back a pointer to an object which allows you to get the
information in various formats. The following is sample code to show the use
of these various objects.
// Terminal object already created called term
CclSecAttr *pAttrblock; // pointer to security attributes
CclSecTime *pDTinfo; // pointer to Date/Time information
try {
pAttrblock = term->verifyPassword();
pDTinfo = pAttrblock->lastVerifiedTime();
cout

|
|
|
Chapter 7. Programming in Java
Overview of the programming interface for Java
This chapter introduces the classes, interfaces, and beans, that make up the
public programming interface of CICS Transaction Gateway.
v Classes for writing Java client programs
– com.ibm.ctg.client.JavaGateway
– com.ibm.ctg.client.ECIRequest
– com.ibm.ctg.client.EPIRequest
– com.ibm.ctg.client.ESIRequest
– com.ibm.ctg.client.CicsCpRequest
– com.ibm.ctg.client.Callbackable (interface)
For more information, see “Writing Java client programs” on page 74.
v Classes for implementing security, using SSL, JSSE, and RACF ®
– com.ibm.ctg.security.SSLightServerSecurity
– com.ibm.ctg.security.JSSEServerSecurity
– com.ibm.ctg.security.SystemSSLServerSecurity (z/OS only)
– com.ibm.ctg.security.ServerSecurity
– com.ibm.ctg.security.ClientSecurity
– com.ibm.ctg.util.RACFUserid (z/OS only)
For more information, see “CICS Transaction Gateway security classes” on
page 111.
v EPI support classes
– com.ibm.ctg.epi.AID
– com.ibm.ctg.epi.EPIGateway
– com.ibm.ctg.epi.Field
– com.ibm.ctg.epi.FieldData
– com.ibm.ctg.epi.Map
– com.ibm.ctg.epi.MapData
– com.ibm.ctg.epi.Screen
– com.ibm.ctg.eoi.EPISecurityAttrs
– com.ibm.ctg.epi.Terminal
– com.ibm.ctg.epi.TerminalSession (interface)
– com.ibm.ctg.epi.TerminalInterface
– com.ibm.ctg.epi.Session (interface)
– com.ibm.ctg.epi.EPIException, with the following subclasses:
- com.ibm.ctg.epi.EPIGatewayException
- com.ibm.ctg.epi.EPIRequestException
- com.ibm.ctg.epi.EPISecurityException
- com.ibm.ctg.epi.EPITxnFailedException
© Copyright IBM Corp. 2002 73

Overview
- com.ibm.ctg.epi.TerminalException
- com.ibm.ctg.epi.EPIMapException
- com.ibm.ctg.epi.EPI3270Exception
- com.ibm.ctg.epi.EPIFieldException
- com.ibm.ctg.epi.EPIScreenException
These classes are not available for CICS Transaction Gateway for z/OS.
For more information, see “EPI support classes” on page 87.
v EPI bean classes
– com.ibm.ctg.epi.EPITerminal Class
– com.ibm.ctg.epi.ScreenEvent Class
– com.ibm.ctg.epi.ScreenEventListener interface
– com.ibm.ctg.epi.ScreenHandler Class
– com.ibm.ctg.epi.TerminalEvent Class
– com.ibm.ctg.epi.TerminalEventListener interface
These classes are not available for CICS Transaction Gateway for z/OS.
For more information, see “EPI beans” on page 101.
Note: It may appear that there is a greater emphasis on EPI programming
(support classes, beans) compared to ECI programming in CICS
Transaction Gateway. This is a consequence of the nature of these
interfaces. For more information on the ECI and EPI interfaces, see
CICS Transaction Gateway: Programming Reference.
Online information on CICS Transaction Gateway classes and interfaces is
provided in the Javadoc (in HTML format).
Writing Java client programs
This section provides an introduction to writing Java client programs for the
CICS Transaction Gateway.
The CICS Transaction Gateway provides the following basic classes for
writing Java client programs:
com.ibm.ctg.client.JavaGateway
This class represents the logical connection between a program and a
CICS Transaction Gateway. You need a JavaGateway object for each
CICS Transaction Gateway that you want to talk to.
com.ibm.ctg.client.ECIRequest
This class contains the details of an ECI request to the Gateway. This
class takes strings for various parameters. If you specify a string that
is too long, the string is truncated to the maximum length.
74 CICS Transaction Gateway: Programming Guide

Writing Java client programs
com.ibm.ctg.client.EPIRequest
This class contains the details of an EPI request to the Gateway. This
class takes strings for various parameters. If you specify a string that
is too long, the string is truncated to the maximum length.
com.ibm.ctg.client.ESIRequest
This class contains the details of an ESI request to the Gateway.
com.ibm.ctg.client.CicsCpRequest
This class contains the details of the codepage used by the Client
daemon.
com.ibm.ctg.client.Callbackable
The asynchronous model supported by the CICS Transaction Gateway
allows the use of callback objects. This interface defines the methods
that a Callbackable object must provide.
Flow of program control
At the simplest level, the flow of program control needed to write a simple
CICS Transaction Gateway Java client program is as follows:
1. The Java program creates and opens an instance of a
com.ibm.ctg.client.JavaGateway object.
v The default JavaGateway constructor creates a blank JavaGateway
object. You must then set the correct properties in this object using the
relevant set methods. The JavaGateway is then opened by calling the
open method.
v Two other JavaGateway constructors, basic and extended, simplify the
creation of a JavaGateway by setting the relevant properties. On return
from a successful call to the basic constructor, the resultant JavaGateway
is open and connected to the requested CICS Transaction Gateway.
2. The Java program creates an instance of one of the Gateway request
classes containing the request that it wants to make, that is:
v A com.ibm.ctg.client.ECIRequest is created for an ECI request
v A com.ibm.ctg.client.EPIRequest is created for an EPI request
v A com.ibm.ctg.client.ESIRequest is created for an ESI request
v A com.ibm.ctg.client.CicsCpRequest is created for querying the codepage
of the Client daemon it is connected through.
3. The Java program then flows the request to the CICS Transaction Gateway
using the flow method of the JavaGateway object.
4. The Java program checks the return code of the flow operation to see
whether the request was successful.
5. The program continues to create request objects and flow them through
the JavaGateway object, as appropriate.
6. The Java program then closes the JavaGateway object.
Chapter 7. Programming in Java 75

Writing Java client programs
JavaGateway
The JavaGateway represents a logical connection between your program and
the CICS Transaction Gateway when you specify a remote protocol. If you
specify a local connection, you connect directly to the CICS server, bypassing
any CICS Transaction Gateway servers.
For example you may specify a remote CICS Transaction Gateway server by
suppling a URL such as tcp://acmectg.acme.com:2006. To use the local
protocol, specify a URL of local:.
Protocols
The JavaGateway supports the following protocols :
v TCP/IP
v SSL
v HTTP
v HTTPS (using an applet, or if your Java environment supports HTTPS. For
example, JSSE provides this support.)
v Local
When you create a JavaGateway you determine the protocol to use, and if
required, the connection details of the remote CICS Transaction Gateway
server (network address and port number). With the JavaGateway class you
can either specify this information using the setAddress, setProtocol and
setPort methods, or you can provide all the information in URL form of
Protocol://Address:Port. You can use the setURL method or pass the URL into
one of the JavaGateway constructors.
JavaGateway security
When you connect to a remote CICS Transaction Gateway, resources allocated
to a particular connection, and identifiers specified on the request objects on a
particular connection, are available only to that connection:
ECI Requests
Logical unit of work (LUW) ids and message qualifiers can only be used
on the same JavaGateway that created or assigned them. This is a security
feature. It stops programs that are connected to the same CICS Transaction
Gateway server from manipulating the LUW ids of another application, or
from using the message qualifier to request its messages. For example,
attempts to get a specific reply to a message from a different JavaGateway
will result in an ECI_ERR_NO_REPLY return code.
EPI Requests
76 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Writing Java client programs
Terminal ids can only be used on the same JavaGateway that created the
terminal. Again, this is a security feature to stop other programs that
connect to the same CICS Transaction Gateway from manipulating that
terminal.
If you specify the local: protocol, the behavior is different. All JavaGateways
that are created in the same JVM (that is, the same process) have access to
each other’s allocated resources or specified indentifiers.
SSL JavaGateway
There are two ways to define the KeyRing or KeyStore, and password, to be
used by a SSL JavaGateway:
Single KeyRing or KeyStore for all SSL JavaGateways in same JVM
Invoke the static method setKeyRing(String key, String password). This
defines a JVM wide KeyRing class, or KeyStore, with associated password,
to use for all SSL JavaGateways created. For example:
SslJavaGateway.setKeyRing(″../keys/mykeystore.jks″, ″passphrase″);
Invoke the static method getKeyRing() to determine the name of the
KeyRing or KeyStore. For example
String JVMWideKeyStore = SslJavaGateway.getKeyRing();
Different KeyRing or KeyStore for each SSL JavaGateway
For each JavaGateway, for which you want a different KeyRing or
KeyStore, specify a properties object that defines properties specific to the
protocol used. Currently, SSL is the only protocol that has any properties
defined. These properties are:
JavaGateway.SSL_PROP_KEYRING_CLASS
Defines the KeyRing class, or KeyStore to be used.
JavaGateway.SSL_PROP_KEYRING_PW
Defines the password to use for the KeyRing, or KeyStore.
For an SSL JavaGateway you must specify both of these properties. If
specified, these properties override the JVM wide definitions of the
KeyRing or KeyStore, and password, for that SSL JavaGateway.
The following example creates an SSL JavaGateway with a specific
KeyStore and password:
Properties sslProps = new Properties();
sslProps.setProperty(JavaGateway.SSL_PROP_KEYRING_CLASS, "../keys/mykeystore.jks");
sslProps.setProperty(JavaGateway.SSL_PROP_KEYRING_PW, "passphrase");
JavaGateway mySslGW = new JavaGateway("ssl://mysystem.com", 8050, sslProps);
Chapter 7. Programming in Java 77

|
|
|
|
|
|
|
|
|
Writing Java client programs
You can also use the setProtocolProperties method before invoking open
on a JavaGateway. You cannot change the protocol properties when the
JavaGateway is open; any attempt to do so causes an IOException to be
thrown.
Note: The getKeyRing() method does not return the name of the specific
KeyRing or KeyStore created this way. It still returns the JVM wide
settings, which could be null if the setKeyRing() method has not
been called.
Flowing Requests
Once you have created and opened a JavaGateway, you flow requests through
it. Create the appropriate request (for example, an ECIRequest) and pass it
into the flow method. The request is then sent as follows:
v To the CICS Transaction Gateway server to be executed if you have a
remote JavaGateway
v Direct to CICS if you are using a local JavaGateway
ECIRequest
To make ECI type calls to CICS you need to create ECIRequest objects. For
more information on these objects refer to the CICS Transaction Gateway:
Programming Reference guide.
Callbacks
ECIRequest supports callback objects. A callback object, which must
implement the Callbackable interface, receives the results of the flow via the
setResults method. Once the results have been applied, a new thread is
started to execute the run method.
You can specify a callback object for all ECIRequest call types (not just
asynchronous call types). In the case of synchronous calls the results are
passed to your Callbackable object as well as to your ECIRequest object in the
flow request.
Message qualifiers
Message qualifiers provide a way to make an asynchronous ECI Request call,
and retrieve the results later. (In an asynchronous call, the flow can continue
without waiting for the results of the request.) In order to be able to retrieve
those results you must tag your request call with a number. The number
(known as the message qualifier) is then used to identify the results for that call.
For remote CICS Transaction Gateway connections, the message qualifier must
be unique within the CICS Transaction Gateway server. If you attempt to
make a request and provide a message qualifier value which is already in use,
you will get an error message telling you that you cannot use that message
qualifier. The automatic message qualifier generator feature of ECIRequest
78 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
|
|
Writing Java client programs
avoids this problem. Turn it on by invoking the method
setAutoMsgQual(true) on your ECIRequest object. This will assign a message
qualifier that is unique on all asynchronous requests (ECI_ASYNC,
ECI_ASYNC_TPN, ECI_STATE_ASYNC, ECI_STATE_ASYNC_JAVA), when
the request is flowed. The value contained in the ECIRequest after the flow
can be used to retrieve the results when a call type of
ECI_GET_SPECIFIC_REPLY and ECI_GET_SPECIFIC_REPLY_WAIT are used.
For remote connections you cannot get replies on a different connection to the
one that flowed the original request with a message qualifier; see
“JavaGateway” on page 76.
If you use ASYNC calls with message qualifiers, you might have to pass a
userid and password when you retrieve the reply using one of the various
GET_REPLY type calls. The userid and password are not used to validate
whether the reply can be retrieved; they are passed to the gateway to hold in
case security is required to clean up (BACKOUT) an LUW if the connection is
closed or broken before the application can finish its work.
For a local connection, the message qualifier should be unique for each
request, although this is not enforced. Also, any connection can get a message
using a message qualifier, even if the request was flowed down a different
connection, provided the JavaGateways are within the same JVM. However, it
is recommended that you use the automatic message qualifier generation:
v To avoid problems resulting from reusing the same message qualifier
v To allow you to switch your application between local and remote
connection
Message qualifiers are not supported on CICS Transaction Gateway for z/OS.
Common Connector Framework and CICSELUW flag
If you use the ECI CCF Connector with a real Coordinator, you must set the
CICSELUW flag on the ECIInteractionSpec to TRUE. The default is TRUE. If
CICSELUW is FALSE, the ECI Resource is not registered with the Coordinator,
and you cannot extend logical units of work as expected.
EPIRequest
To make EPI type calls to CICS you need to create EPIRequest objects. For
more information on these objects, refer to CICS Transaction Gateway:
Programming Reference. Note that CICS Transaction Gateway for z/OS does not
support EPIRequest objects.
Using the EPIRequest class
It is recommended that you use EPI beans or the CICS Transaction Gateway
EPI support classes if you are writing programs using the EPI. However, read
this section if you intend to use the EPIRequest class.
Chapter 7. Programming in Java 79

Writing Java client programs
When connecting to CICS using EPI, a Java application is acting as a terminal
to CICS. It is, therefore, important to be aware of the 3270 data streams that
might flow from CICS, and the 3270 data streams that might be expected in
reply. After an event has been returned to a Java application, the size field of
the EPIRequest object indicates the size of the data array returned.
It is also important to be aware of the principles and restrictions governing
EPI programming, and to be aware that there might be minor differences in
the working of the EPI code on different operating systems. For example, if
you are running a CICS Transaction Gateway on Windows, you will probably
need to send Transaction identifiers in the data array of the EPIRequest object,
rather than in the EPIRequest object’s Transid field.
When getting events from CICS it is recommended that you use the
EPI_WAIT option, and ensure that the size field of the EPIRequest object is set
to the maximum size of the 3270 data stream that CICS might return.
Parameter lengths: When using the EPIRequest class it is important to note
that the various parameters have maximum lengths. Any
parameters passed exceeding these lengths will be
truncated.
Generally, EPI programs written using the CICS Transaction Gateway should:
1. Open a connection to the Gateway.
2. Add a terminal.
3. Start a transaction.
4. Get an event until either:
v the event received is an end transaction or a converse
v or the error received is severe
5. If the event received is a converse, send the reply and return to the get
event loop.
6. If the event received is an end transaction, delete the terminal and do a
last get event to obtain the end terminal event.
7. Close the connection to the Gateway.
Terminal Indexes
For remote connections, terminal indexes can only be used on the connection
to which they were assigned. See “JavaGateway” on page 76 for more
information. For local connections, all local JavaGateways can access terminal
indexes on other local JavaGateways, provided they are in the same JVM.
80 CICS Transaction Gateway: Programming Guide

Writing Java client programs
Setting up the CLASSPATH
Before you write any Java client programs, update the CLASSPATH
environment variable to include the jar files supplied with CICS Transaction
Gateway. For example, on Windows:
CLASSPATH = \classes\ctgclient.jar;
\classes\ctgserver.jar
The ctgserver.jar file is required in CLASSPATH only for JavaGateways using
the local URL.
For more information on setting CLASSPATH, see the CICS Transaction
Gateway: Administration book for your operating system.
Codepage conversion
If the code page of the application is different from the code page of the
server, conversion must be performed on the data in the COMMAREA. To do
this, you need to make use of CICS-supplied resource conversion capabilities
on the server, such as the DFHCNV macro definitions.
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:
CCL6664E: 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.
Performance issues
There are several performance issues to consider when you run Java client
applications. The Java Virtual Machine (JVM) allocates a fixed size of stack
space for each running thread in an application. You can usually control the
amount of space that Java allocates by setting limits on the following sizes:
v The native stack size, allocated when running native JIT (Just-In-Time)
compiled code.
v The Java stack size, allocated when running Java Bytecode.
v The initial Java heap size.
v The maximum Java heap size.
How you set these limits depends on your JVM. Refer to your Java
documentation for more information.
Chapter 7. Programming in Java 81

Writing Java client programs
Tracing in Java client programs
You can control tracing in Java client programs using:
v calls to the com.ibm.ctg.client.T class
For example, from within a user application:
if (getParameter("trace") != null)
{
T.setOn(true);
}
where trace is a startup parameter that can be set on the user program.
v Gateway.T system properties
For example:
java -Dgateway.T=on com.usr.smp.test.testprog1
which specifies full debug for testprog1.
For more information on the use of system properties, refer to your Java
documentation.
The following is an explanation of the various trace levels available. The
names of calls and properties are case sensitive.
Trace level Standard
com.ibm.ctg.client.T call
T.setOn (true/false)
System property
gateway.T.trace=on
Definition The standard option for application tracing.
By default, it displays only the first 128 bytes
of any data blocks (for example the commarea,
or network flows).
This trace level is equivalent to the Gateway
trace set by the ctgstart –trace option.
Trace level Full Debug
com.ibm.ctg.client.T call
T.setDebugOn (true/false)
System property
gateway.T=on
Definition The debugging option for application tracing.
82 CICS Transaction Gateway: Programming Guide

Writing Java client programs
By default, it traces out the whole of any data
blocks. The trace contains more information
about the CICS Transaction Gateway than the
standard trace level.
This trace level is equivalent to the Gateway
debug trace set by the ctgstart –x option.
Trace level Exception Stacks
com.ibm.ctg.client.T call
T.setStackOn (true/false)
System property
gateway.T.stack=on
Definition The exception stack option for application
tracing.
It traces most Java exceptions, including
exceptions which are expected during normal
operation of the CICS Transaction Gateway.
No other tracing is written.
This trace level is equivalent to the Gateway
stack trace set by the ctgstart –stack option.
You can further configure the tracing by using the following options:
com.ibm.ctg.client.T call
T.setTFile(true,filename)
System property
gateway.T.setTFile=filename
Option usage The value filename specifies a file location for
writing of trace output. This is as an
alternative to the default output on stderr.
Long filenames must be surrounded by
quotation marks, for example: ″trace output
file.log″
com.ibm.ctg.client.T call
T.setTruncationSize(number)
System property
gateway.T.setTruncationSize=number
Option usage The value number specifies the maximum size
of any data blocks that will be written in the
trace. Any positive integer is valid. If you
specify a value of 0, then no data blocks will
Chapter 7. Programming in Java 83

Writing Java client programs
be written in the trace. If a negative value is
assigned to this option the exception
java.lang.IllegalArgumentException will be
raised.
com.ibm.ctg.client.T call
T.setDumpOffset(number)
System property
gateway.T.setDumpOffset=number
Option usage The value number specifies the offset from
which displays of any data blocks will start. If
the offset is greater than the total length of
data to be displayed, an offset of 0 will be
used. If a negative value is assigned to this
option the exception
java.lang.IllegalArgumentException will be
raised.
com.ibm.ctg.client.T call
T.setTimingOn (true/false)
System property
gateway.T.timing=on
Option usage Specifies whether or not to display
time-stamps in the trace.
Use the options in addition to one of the directives to switch tracing on.
For example, the following switches standard tracing on, and sets the
maximum size of any data blocks to be dumped to 20 000 bytes:
java -Dgateway.T.trace=on -Dgateway.T.setTruncationSize=20000
Making ECI calls on z/OS
The CICS Java classes allow you to create ECIRequest objects that represent
calls to the ECI.
Program link calls
You can create ECIRequest objects that represent requests for synchronous and
asynchronous program link calls (ECI_SYNC and ECI_ASYNC call types).
The following restrictions apply:
v The length of the communication area (COMMAREA) passed to ECI must not
exceed 32 659 bytes.
v You cannot use message qualifiers, such as the variable Message_Qualifier,
or the methods isAutoMsgQual(), setAutoMsgQual(),
setMessageQualifier(), orsetMessageQualifier()
84 CICS Transaction Gateway: Programming Guide

Writing Java client programs
v You cannot use reply solicitation call types such as GET_REPLY,
GET_REPLY_WAIT, GET_SPECIFIC_REPLY, orGET_SPECIFIC_REPLY_WAIT
v If you use the ECI_ASYNC call type, you must use the callbackable
interface
v You cannot use the methods getECITimeout(), orsetECITimeout(). Asan
alternative, set the TIMEOUT parameter in the EXCI options table
DFHXCOPT. For details, see the CICS External Interfaces Guide, SC34-6006.
Status information calls
The ECI status information calls (ECI_STATE_SYNC and ECI_STATE_ASYNC
call types) return their results in a CICS communication area. Because the
contents of the communication area are platform dependent, the ECIRequest
class provides help with interpreting the results of a status information call:
v Public variables to hold the results of a status information call in a
platform-independent manner
v Two call types (ECI_STATE_SYNC_JAVA and ECI_STATE_ASYNC_JAVA)
that return the results of a status information call in the public variables
rather than in a communication area
v Methods to interpret the contents of the public variables as strings for
display
Only the ECI_STATE_IMMEDIATE value for the extend mode in status
information calls is supported.
CICS security considerations
The CICS Transaction Gateway for z/OS region is an EXCI user, so the
following security considerations apply:
v If the user ID of the CICS Transaction Gateway for z/OS address space is
the same as the user ID of the CICS address space:
– LINK security checking is not performed.
– Surrogate user checking is performed, so the user ID of the CICS
Transaction Gateway for z/OS address space must be authorized to use
the user ID passed on the ECI call.
v If the user ID of the CICS Transaction Gateway for z/OS address space is
different from the user ID of the CICS address space, LINK security checking
is performed according to the setting of ATTACHSEC for the connection.
The user ID passed on the ECI call is validated.
v The userid and password coded on the ECIRequest object is validated with
RACF ® for every EXCI call.
v Userid and password authentication can be disabled for each EXCI call.
This is done using the AUTH_USERID_PASSWORD environment variable
in the ctgstart script. See Setting environment variables, inCICS Transaction
Gateway: z/OS Administration, for more information.
Chapter 7. Programming in Java 85

Writing Java client programs
ECI return codes and server errors on z/OS
This section describes how the return codes from the EXCI are returned to the
user of the ECIRequest object.
Table 6 shows how EXCI return codes map to ECI return codes. The EXCI
return codes are documented in the CICS External Interfaces Guide.
Table 6. EXCI return codes and ECI return codes
EXCI return codes ECI symbolic names/return codes rc
201, 203 ECI_ERR_NO_CICS –3
202 ECI_ERR_RESOURCE_SHORTAGE –16
401, 402, 403, 404, 410, 411,
412, 413, 418, 419, 421
ECI_ERR_SYSTEM_ERROR –9
422 ECI_ERR_TRANSACTION_ABEND –7
423 ECI_ERR_SECURITY_ERROR –27
601, 602, 603, 604, 605, 606,
607, 608, 621, 622, 623, 627,
628
ECI_ERR_SYSTEM_ERROR –9
609 ECI_ERR_SECURITY_ERROR –27
624 ECI_ERR_REQUEST_TIMEOUT –5
Making EPI calls on z/OS
The CICS Java classes allow you to create EPIRequest objects that represent
calls to the EPI. You set the public variable Call_Type in an EPIRequest object
to specify which EPI call you wish to make. The results of the EPI call are
returned in the object after you use the flow method of the JavaGateway
object.
However, as you might expect, attempts to flow an EPIRequest object are
rejected. The return code EPI_ERR_FAILED is returned. You should not use
EPI_GetSysError to attempt to get more information. If you want to run
transactions in the manner of the EPI, you should use the ECI and set up a
request for DFHWBTTA. This is described in the CICS Internet guide.
EXCI considerations on z/OS
Version 2 of the EXCI is supported, and it provides support for eci_transid
and resolves previous problems with ASCII/EBCDIC conversion.
If you use EXCI Version 2 and eci_tpn is specified on the ECI request, then
the definition of the user mirror transaction should now specify
PROGRAM(DFHMIRS), regardless of whether the transacton is defined as
local or remote.
86 CICS Transaction Gateway: Programming Guide

EPI support classes
This chapter:
v Gives an overview of the EPI support classes
v Explains how to use the EPI support classes
v Describes how to handle exceptions
v Describes how to disconnect terminals
v Describes the encoding of 3270 datastreams
v Explains how to convert BMS maps and use the Map class
v Describes how to use the EPIRequest class
EPI support classes
Overview of EPI support classes
Many existing CICS server applications are written for 3270 terminal
interfaces, and CICS has some powerful capabilities for dealing with these
data streams, including Basic Mapping Support (BMS).
The External Presentation Interface (EPI) provides a mechanism for client
applications to communicate with transactions on a server and to handle 3270
data streams. A client application using EPI connects to CICS as if it were a
3270 terminal, and must send and receive 3270 data streams.
The CICS Transaction Gateway EPI support classes make it simpler for a Java
programmer to access the facilities that the EPI provides:
v Connecting 3270 sessions to CICS servers
v Starting CICS transactions
v Sending and receiving 3270 data streams
You do not need a detailed knowledge of 3270 data streams. The classes
provide higher-level constructs for handling 3270 data streams as follows:
v General purpose Java classes for handling 3270 data streams, such as fields
and attributes, and CICS transaction routing data, such as transaction ID.
v Generation of Java classes for specific CICS applications from BMS map
source files. These classes allow client applications to access data on 3270
panels, using the same field names as used in the CICS server BMS
application.
Note: These classes do not contain any specific support for 3270 datastreams
that contain DBCS fields. However they do not support 3270
datastreams that contain mixed SBCS and DBCS fields.
The BMS conversion utility is a tool for statically producing Java class source
code from a CICS BMS mapset. See “Converting BMS maps and using the
Map class” on page 100.
Chapter 7. Programming in Java 87

EPI support classes
The EPI support classes are similar to the C++ EPI classes (the objects
required and the methods to manipulate them are similar).
In the examples in this chapter, statements similar to the following are
assumed:
import com.ibm.ctg.epi.*;
import java.io.*;
The EPI support classes are as explained in the following, see the HTML
Javadoc for a more comprehensive explanation.
com.ibm.ctg.epi.AID
Represents an AID (attention identifier) character to be sent to CICS.
com.ibm.ctg.epi.EPIGateway
Connects to the CICS Transaction Gateway. This class also has
methods that obtain information on CICS servers accessible to the
client.
com.ibm.ctg.epi.Field
Supports a single field on a virtual screen and provides access to field
text and attributes.
com.ibm.ctg.epi.FieldData
Contains information about a single field, that is, its row and column
position and length.
com.ibm.ctg.epi.Map
Provides access to Field objects using BMS map information. The
BMSMapConvert utility generates classes derived from Map.
com.ibm.ctg.epi.MapData
Contains information about a BMS map, that is, its size, number of
fields, and so on.
com.ibm.ctg.epi.Screen
The Terminal object for a terminal has a virtual screen associated with
it. The Screen class contains a collection of Field objects and methods
to access these objects. It also has methods for general screen
handling.
com.ibm.ctg.epi.Terminal
Controls a 3270 terminal connection to CICS. The Terminal class
handles CICS conversational, pseudo-conversational, and ATI
transactions. One application can create many Terminal objects.
com.ibm.ctg.epi.TerminalInterface (interface)
The Terminal class implements this interface.
88 CICS Transaction Gateway: Programming Guide

EPI support classes
com.ibm.ctg.epi.TerminalSession (interface)
Defines the behavior of a terminal in session, that is, a terminal with
an associated Session object. TerminalInterface extends this with
functions that allow the Session object to be changed.
com.ibm.ctg.epi.Session (interface)
Controls communication with the server in synchronous and
asynchronous modes. Application classes can implement the Session
interface to handle replies from the server.
com.ibm.ctg.epi.EPIException
This is the superclass to exceptions that can be thrown by the EPI
support classes.
com.ibm.ctg.epi.EPIGatewayException
This exception is thrown when general problems relating to
the gateway occur.
com.ibm.ctg.epi.EPIRequestException
This exception is thrown when problems relating to EPI
Requests occur.
com.ibm.ctg.epi.EPISecurityException
This exception is thrown when problems relating to security
requests occur.
com.ibm.ctg.epi.EPITxnFailedException
This exception is thrown when problems running a
transaction occur.
com.ibm.ctg.epi.TerminalException
This exception is thrown when the Terminal class detects
problems.
com.ibm.ctg.epi.EPIMapException
This exception is thrown by the autogenerated map classes if
a map is not valid.
com.ibm.ctg.epi.EPI3270Exception
This exception is thrown when problems occur trying to
process a 3270 datastream.
com.ibm.ctg.epi.EPIFieldException
This exception is thrown if problems occur interacting with
field objects.
com.ibm.ctg.epi.EPIScreenException
This exception is thrown if problems occur interacting with
screen objects.
Chapter 7. Programming in Java 89

EPI support classes
Using the EPI support classes
This section describes how to use the EPI support classes. Examples of code
are included.
Establishing a terminal to CICS: The following describes how to establish a
terminal to a CICS Server. For more information about EPI and terminal
properties, such as Signon Capability and Read Timeouts, see CICS Transaction
Gateway: Programming Reference.
EPIGateway: Create a JavaGateway object (to start a connection to the CICS
Transaction Gateway) before attempting to connect a terminal to CICS. The
EPIGateway class provides methods to access information about CICS servers
that are accessible from the CICS Transaction Gateway, and it can be used
instead of the JavaGateway class.
try {
EPIGateway eGate = new EPIGateway("local:" ,0);
int numSystems = eGate.serverCount();
System.out.println("Number of servers:" + numSystems);
for (int sysCount = 1; sysCount

EPI support classes
To create a terminal using the default constructor, first instantiate a
terminal, and then use the appropriate setter methods to set the required
properties. Use only the setters that apply to a basic terminal. These
methods are:
v setGateway
v setServerName
v setDeviceType
v setNetName
v setSession
All properties, with the exception of setGateway, are optional and have a
default setting of null. After you have defined your terminal, connect it to
the CICS server using the connect() method. Use only this version of the
connect() method. The other versions of the connect method are allowed
only for an extended terminal. See “Connecting an extended terminal to
CICS” on page 93 and “Synchronization and sessions” on page 94 for
further information.
try {
EPIGateway eGate = new EPIGateway("tcp://MyGateway",2006);
Terminal term = new Terminal();
term.setGateway(eGate);
term.setServerName("CICS1");
term.connect();
}
catch (IOException ioEx) {
ioEx.printStackTrace();
}
catch (EPIException epiEx) {
epiEx.printStackTrace();
}
Basic terminal constructor
The second way is to use the basic terminal constructor. This sets all the
required properties and automatically connects you to the CICS Server.
try {
EPIGateway eGate = new EPIGateway("tcp://MyGateway",2006);
Terminal term = new Terminal(eGate, "CICS1", null, null);
}
catch (IOException ioEx) {
ioEx.printStackTrace();
}
catch (EPIException epiEx) {
epiEx.printStackTrace();
}
Exceptions: As the examples show, exceptions must be caught irrespective
of which method is used to construct a basic terminal.
Chapter 7. Programming in Java 91

EPI support classes
The other optional setter is setSession. Sessions are discussed in
“Synchronization and sessions” on page 94.
Extended terminal: There are two ways to construct an extended terminal:
v Using the default constructor
v Using the extended terminal constructor
Default terminal constructor
To create a terminal using the default constructor, you first instantiate a
terminal, and then use the appropriate setter methods on that object. As
for the basic terminal, setGateway is mandatory, with setDeviceType,
setNetName and setServer being optional. The following setters define the
properties for the extended terminal. Using any of these setters implies
that you are creating an extended terminal:
v setSignonCapability (Default = signon capablez)
v setUserid (Default = null)
v setPassword (Default = null)
v setReadTimeout (Default = 0)
v setEncoding (Default = null)
v setInstallTimeout (Default = 0)
try {
EPIGateway eGate = new EPIGateway("tcp://MyGateway",2006);
Terminal term = new Terminal();
term.setGateway(eGate);
term.setServerName("CICS1");
term.setSignonCapability(Terminal.EPI_SIGNON_INCAPABLE);
term.setUserid(userid);
term.setPassword(password);
term.connect();
}
catch (IOException ioEx) {
ioEx.printStackTrace();
}
catch (EPIException epiEx) {
epiEx.printStackTrace();
}
Once you have defined your terminal, you can connect it to CICS
(see“Connecting an extended terminal to CICS” on page 93).
Extended terminal constructor
The extended terminal constructor sets all required properties at
construction time:
try {
EPIGateway eGate = new EPIGateway("tcp://MyGateway",2006);
Terminal term = new Terminal(eGate, "CICS1", null, null,
Terminal.EPI_SIGNON_INCAPABLE, userid,
92 CICS Transaction Gateway: Programming Guide

term.connect();
}
catch (IOException ioEx) {
ioEx.printStackTrace();
}
catch (EPIException epiEx) {
epiEx.printStackTrace();
}
password,0, null);
EPI support classes
Unlike the basic terminal constructor the extended terminal constructor
does not automatically connect to CICS. This must be done explicitly
using one of the following methods:
Connecting an extended terminal to CICS: The connect methods that can be
used are as follows:
Connect()
This method connects the terminal to CICS using the session property
and install timeout property.
Connect(installTimeout)
This method connects the terminal to CICS using the session property,
but updates the install timeout property to that supplied.
Connection(Session, installTimeout)
This method connects the terminal to CICS, updating the current
session property with the supplied session object, and updating the
install timeout property with that supplied. Sessions are discussed in
“Synchronization and sessions” on page 94.
Using send to start and interact with transactions: Once you have
established a terminal to CICS, you use send methods to start a new
transaction or to send a screen to CICS:
try {
term.send("EP01",null);
}
catch (EPIException ex) {
ex.printStackTrace();
}
You can also build your own screen to start a transaction. Screen manipulation
and fields are discussed in “Accessing fields on CICS 3270 screens” on
page 94. The following shows an alternative way of starting a transaction
using the Screen and Field objects:
try {
Screen scr = term.getScreen();
Field fld = scr.field(1);
fld.setText("EP01");
term.send();
Chapter 7. Programming in Java 93

EPI support classes
}
catch (EPIException ex) {
ex.printStackTrace();
}
Accessing fields on CICS 3270 screens: When a terminal connection to CICS
has been established, the Terminal, Screen and Field objects are used to
navigate through the screens presented by the CICS server application,
reading and updating screen data as required.
The Screen object is created by the Terminal object and is obtained via the
getScreen method on the Terminal object. It provides methods for obtaining
general information about the 3270 screen (for example, cursor position) and
for accessing individual fields (by row/column, screen position or by index).
The following example prints out field contents, ends the CICS transaction (by
returning PF3) and disconnects the terminal:
// Get access to the Screen object
Screen screen = terminal.getScreen();
for ( int i=1; i 0 )
System.out.println( "Field " + i + ": " + field.getText() );
}
// Return PF3 to CICS
screen.setAID( AID.PF3 );
terminal.send();
// Disconnect the terminal from CICS
terminal.disconnect();
The Field class provides access to the text and attributes of an individual 3270
field. You can use these in a variety of ways to locate and manipulate
information on a 3270 screen:
for ( int i=1; i

EPI support classes
blocks until all the information has been received back from the server; an
asynchronous send exits from the method immediately, but still processes the
replies in the background. While information is being received from the
server, the Screen object is updated.
To select synchronous mode, you can either specify null for the session using
the setSession method, or specify a null session when invoking send.
Alternatively, you can implement the session interface and specify that it is a
synchronous session.
To select asynchronous mode, implement the session interface and specify that
it is an asynchronous session.
Implementing the session interface: The session interface defines two methods
that must be implemented: getSyncType and . The following code shows a
sample implementation:
import com.ibm.ctg.epi.*;
public class myASession implements Session {
public int getSyncType() {
return Session.async;
}
public void handleReply(TerminalInterface term) {
System.out.println(
"Reply received Terminal state = " + term.getState());
}
public void handleException(TerminalInterface a, Exception e) {
System.out.println("Exception received:" + e.getMessage());
}
}
This example defines the session as an asynchronous session, because it
returns Session.async on the getSyncType call. To make the session a
synchronous session, you return Session.sync.
The example shows two methods:
handleReply
You must implement the handleReply method. It is called for each
transmission received from CICS. Depending on the design of the
CICS server program, a Terminal send call can result in one or more
replies. The Terminal state property indicates whether the server has
finished sending replies:
Terminal.server
Indicates that the CICS server program is still running and
has further data to send. The client application can process the
current screen contents immediately, or simply wait for
Chapter 7. Programming in Java 95

EPI support classes
96 CICS Transaction Gateway: Programming Guide
further replies. The application cannot disconnect the terminal,
or send the screen to CICS, or start a new transaction.
Terminal.client
Indicates that the CICS server program is now waiting for a
response. The client application should process the screen
contents and send a reply. The application cannot disconnect
the terminal or start a new transaction.
Terminal.idle
Indicates that the CICS server program has completed. The
client application should process the screen contents and
either disconnect the terminal or start a further transaction.
Terminal.failed
Indicates that the transaction has failed to start or complete
for some reason, for example, a conversion transaction has
timed-out waiting for a response from the application. Invoke
the endReason and endReasonString methods for more
information.
Terminal.discon
Indicates that the terminal has been disconnected. Invoke the
endReason and endReasonString methods for more
information.
Terminal.error
Indicates that the terminal is in error state and cannot be
used. Try to disconnect the terminal to ensure that all
resources are cleaned up.
Most client applications will want to wait until the CICS server
program has finished sending data (that is, the Terminal state is client
or idle) before processing the screen. However, some long-running
server programs might send intermediate results or progress
information that can usefully be accessed while the state property is
still server.
The implementation of the handleReply method can read and process
data from the Screen object, update fields as required, set the cursor
position and AID key in preparation for the return transmission to
CICS, and then use the Terminal send method to drive the server
application.
In synchronous mode, handleReply executes on the same thread that
invoked the send. In asynchronous mode, handleReply executes on a
separate thread.

EPI support classes
Note: The handleReply method should never attempt to disconnect a
terminal. The disconnect call might make the application hang
if called from handleReply.
handleException
The handleException method is not specified as part of the session
interface and is optional. The compiler does not force implementation
of the method. The Terminal class invokes this method if it is present
in the Session object.
You must implement the handleException method for asynchronous
mode sends.
It is recommended that you also implement the handleException
method for synchronous mode sends with Automatic Transaction
Initiation (ATI) enabled.
As for the method, the Terminal state property shows information
about the terminal connection.
Exceptions are passed in the Exception object. See “Exception
handling”, for a list of the exceptions that can occur.
Using your session: You can set the session on a terminal by either using the
setSession method, or by passing the session object as part of a send or
connect method. “null” is also accepted as a session, meaning that you have
no listening object in place for replies and exceptions, and that all calls are
synchronous.
ATIs and Read Timeouts: ATI events and Read Timeout events are
asynchronous and can occur at any time during the execution of an
application, providing ATIs are enabled and a Read Timeout value was
specified when creating an extended terminal. If you plan to use these
features, it is recommended that you use an asynchronous session. However,
these features can be used on a synchronous session; in this case, if any events
occur while blocked, will run on the thread that invoked send or disconnect.
If your application is not within a send or disconnect invocation, executes on
a separate thread.
Exception handling
Exceptions can occur when interacting with a terminal. The following is the
exception hierarchy.
Chapter 7. Programming in Java 97

EPI support classes
EPIException
Figure 15. Exception hierarchy
EPI3270Exception
EPIRequestException
EPISecurityException
TerminalException
EPIGatewayException
EPITxnFailedException
EPIFieldException
EPIScreenException
EPIMapException
A description of each exception is given in “Overview of EPI support classes”
on page 87.
The other type of exception that can occur is IOException.
The exceptions provide a field to retrieve an exception-specific error code
which distinguishes the exceptions. The method is getErrorCode().
If you are using either a null session or a synchronous session, and you have
not enabled ATIs and are not using Read Timeouts, all exceptions are thrown
on the application thread. When trying to invoke methods such as connect,
send, or disconnect, wrap the call in a try/catch/finally type block.
When using asynchronous sessions, a problem arises if you have ATIs, or
Read Timeouts, or both, enabled. In this case, exceptions can occur while
within connect/send/disconnect method invocations but also outside of these
calls.
If you use asynchronous sessions, exceptions cannot be thrown on any of the
application threads. If you enable ATIs, or Read Timeouts, or both, it is
recommended that you use asynchronous sessions.
98 CICS Transaction Gateway: Programming Guide

To know when an exception has occurred while not invoking a terminal
method, you can implement the handleException method on the session (see
“Synchronization and sessions” on page 94, for an example). You can
implement it for both synchronous and asynchronous sessions. If the terminal
is unable to throw the exception on the application thread (that is, it is not
blocked on a synchronous call or it is an asynchronous session), this method
is invoked on a separate thread and the exception is passed to it.
Disconnecting terminals
Always make sure that a terminal disconnects without any problems, and that
you disconnect all terminals before your application ends. This ensures that
all resources are cleaned up. There are two types of disconnect:
v PurgeOnDisconnect property is set to false (the default)
v PurgeOnDisconnect property is set to true
Purge attempts to disconnect the terminal even if events are still outstanding
or a transaction is still running. To disconnect with purge, set the property to
true:
term.setPurgeOnDisconnect(true);
term.disconnect();
After successful disconnection, you can reconnect the terminal object by
issuing one of the connect() methods:
term.disconnect();
.....
term.connect();
EPI support classes
Session does not apply to a disconnect call. All disconnects are considered
synchronous.
Extended terminal encoding property
You can specify the encoding in which the resulting 3270 datastream is to be
constructed. When the terminal is connected, the CICS server (providing it
supports EPI Version 2) is informed of the encoding applied to the 3270
datastream. If you specify null, the encoding used by the CICS Transaction
Gateway server is used (or the default encoding of the application if the local
gateway is being used).
Basic terminals always work in the encoding used by the CICS Transaction
Gateway server (or the default encoding of the application if the local
gateway is being used).
Refer to your CICS Server document for more information on supported
codepages.
Chapter 7. Programming in Java 99

EPI support classes
Converting BMS maps and using the Map class
A large proportion of existing CICS applications use BMS maps for 3270
screen output. This means that the server application can use data structures
corresponding to named fields in the BMS map rather than handling 3270
data streams directly. The EPI BMS conversion utility uses the information in
the BMS map source to generate classes specific to individual maps, which
allow fields to be accessed by their names.
The utility generates Java classes that applications can use to access the map
data as named fields within a map object. A class is defined for each map,
allowing field names and lengths to be known at compile time. The generated
classes extend the class Map, which provides general functions required by all
map classes.
Run the BMS map converter utility on the BMS source as follows:
java com.ibm.ctg.epi.BMSMapConvert -p package -name filename.BMS
The utility generates .java files containing the source for the map classes. Use
the -p parameter to specify the package to put the new files into. This saves
you having to edit the files to add the ″package″ statement.
After you have used the EPI BMS utility to generate the map class, use the
base EPI classes to reach the required 3270 screens in the usual way. Then use
the map classes to access fields by their names in the BMS map. The map
classes are validated against the data in the current Screen object.
Using Map classes: The classes generated by the BMS Conversion Utility
have the following features:
v The class name is derived from the map name in the BMS source.
v The class extends Map.
v Two constructors are provided. One constructor takes a Screen parameter
and throws an EPIException, if the screen has not been produced by the
relevant BMS map. The no argument constructor creates a Map that can be
validated against a screen later by using the setScreen method.
v The method field provides access to fields in the map, using the BMS
source field names (provided as constants within the class).
To use the generated Map class, create a Terminal and start a transaction as
usual:
try {
EPIGateway epi = new EPIGateway("jgate", 2006 );
// Connect to CICS server
Terminal terminal = new Terminal( epi, "CICS1234", null, null );
// Start transaction on CICS server
terminal.send( null, "EPIC", null );
MAPINQ1Map map = new MAPINQ1Map( terminal.getScreen() );
100 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
EPI support classes
Field field;
// Output text from "PRODNAM" field
field = map.field(MAPINQ1Map.PRODNAM);
System.out.println( "Product Name: " + field.getText() );
// Output text from "APPLID" field
field = map.field(MAPINQ1Map.APPLID);
System.out.println( "Applid : " + field.getText() );
} catch (Exception exception) {
exception.printStackTrace();
}
In this example the server program uses a BMS map for its first panel, for
which a map class ″MAPINQ1Map″ has been generated. When the map object
is created, the constructor validates the screen contents with the fields defined
in the map. If validation is successful, fields can then be accessed using their
BMS field names instead of by index or position from the Screen object:
BMS Map objects can also be used within the Session handleReply method.
For validation to succeed, the entire BMS map must be available on the
current screen. A map class cannot therefore be used when some or all of the
BMS map has been overlaid by another map or by individual 3270 fields.
EPI beans
This section describes the beans that you can use for EPI functions.
Beans provided in earlier versions of CICS Transaction Gateway
These beans, which previously were provided as part of the CICS Transaction
Gateway product, are now included with the set of sample programs:
v EPIMonitor
v EPIScreenButtons
v EPIBasicScreenHandler
Include the archive \classes\ctgsamples.jar in the classpath
of any programs that use these beans. The EPIBasicScreenHandler bean
includes new functions, such as font and color selection, and an improved
layout.
CICS Transaction Gateway EPI beans Overview
The CICS Transaction Gateway includes high-level EPI classes to allow you to
easily write Java programs that access data from existing CICS 3270
applications.
However, the EPI beans, based on this function, go one step further — you
can create applications that access your existing CICS 3270 screens without any
programming at all. Using any of the large number of new visual application
builder tools, you can quickly and easily create new Java front-ends that can
connect to CICS, run transactions, display data from 3270 screens, and send
Chapter 7. Programming in Java 101

EPI beans
user input back to the server. Note that the EPI beans do not support
double-byte character set (DBCS) fields in 3270 data streams.
Several visual development tools, that allow you to build Java applications
with Java beans, are now available.
To use the beans with a visual development tool, you may need to import or
load the ctgclient.jar file into the tool. Refer to the tool’s documentation to
find out how to do this. Alternatively, you may need to include this file in the
CLASSPATH setting.
Using the beans: Once you have loaded the beans into a suitable visual
development tool, you are ready to start creating an application that uses
them.
Connecting to CICS: Before your application can do anything else, it must
connect to the CICS Transaction Gateway. To do this, you need an
EPITerminal bean. Set the properties of the bean and specify the URL of the
gateway you wish to connect to. In Figure 16 on page 103 you can see an
example of what a property sheet for the bean might look like.
102 CICS Transaction Gateway: Programming Guide

Figure 16. A property sheet for the Terminal Bean
EPI beans
Define the terminal specific properties you require including the CICS to
which you wish to connect. See Figure 17 on page 104 for an example of the
terminal settings property sheet. Refer to the beans reference section for more
information on the various properties. To connect to CICS, call the
EPITerminal’s connect method.
Chapter 7. Programming in Java 103

EPI beans
Figure 17. A Terminal settings property sheet
Starting a transaction: To start a transaction, you can call the EPITerminal’s
startTran method, having previously set the transaction property to the
transaction ID you want to start. Some tools allow you to call the
setTransaction method with a defined parameter when an event occurs.
Alternatively, send an ActionEvent to EPITerminal with the action command
set to the transaction ID that you want to start. The transaction property is set
to that value and the transaction is started as soon as possible. ActionEvents
are generated by buttons, menu items and entry fields (when you select Enter
- the action command is the text).
Handling screens: Once you have started a transaction on the CICS server,
CICS begins sending data back to the EPITerminal bean. When EPITerminal
receives data from CICS, it sends a handleScreen event to all its registered
104 CICS Transaction Gateway: Programming Guide

EPI beans
event listeners. To handle the data sent by CICS, you create beans called
screen handlers and connect them to the EPITerminal’s handleScreen event.
You can use one of the tools provided to generate screen handler beans
automatically. The automatically-generated screen handler beans give you
access to some of the data in the screen in the form of bound properties. You
then create your own user interface (from other beans) to allow those
properties to be displayed and changed.
Sending data back to CICS: Once you have received a screen from CICS and
viewed and edited it as required, you must send it back to CICS to continue
processing. If you are using an automatically generated bean, then this means:
v Setting the screen handlers AID property to the required AID value
v Calling the send method of the screen handler or EPITerminal
Another way to achieve the same result is to send an ActionEvent to the
screen handler with the action command set to an AID value (for example:
enter or PF3). The AID is then set to that value and the screen is sent to CICS.
ActionEvents are generated by buttons, menu items, and entry fields.
Disconnecting from CICS: When your application is finished, ensure that the
EPITerminal’s disconnect method is called to disconnect the terminal from
CICS. When disconnect is invoked, if the terminal is not in the idle state (i.e.
no transactions running) EPITerminal sends the handleScreen event to its
registered event listeners, requesting that they exit any running transactions.
The default behaviour of the generated screen handlers is to send the AID PF3
to the CICS server. If you know that this will not work for a particular
transaction you are using, generate a screen handler for the relevant screen,
and customise it to ensure it can exit that screen. If you have not specified
purge on disconnect, then the disconnect will only occur if the transaction is
ended.
Example: This example demonstrates the basic principles involved in using
the beans.
1. Add the ctgsamples.jar file to your CLASSPATH environment variable. This
provides access to the EPIBasicScreenHandler and the EPIScreenButtons
beans used in this example.
2. Using your preferred bean composer tool, create an EPITerminal, and look
at its properties. Set the URL property to the address of the Gateway, for
example: tcp://jbloggs.hursley.ibm.com:2006. The terminal settings
property allows you to set further terminal settings, such as the name of
your CICS server.
3. Create two buttons labelled Connect and Disconnect. Connect the
Connect button’s actionPerformed event to the connect method on
Chapter 7. Programming in Java 105

EPI beans
EPITerminal. Similarly, connect the Disconnect button to the EPITerminal’s
disconnect method. You can now connect to the CICS server and
disconnect again.
4. Create an EPIBasicScreenHandler. This is a visual part that is able to
display data sent from CICS. Connect the EPITerminal’s handleScreen
event to the EPIBasicScreenHandler’s handleScreen method. Check that
the event data is passed to EPIBasicScreenHandler.
5. Connect the Connect button’s actionPerformed event to the startTran
method on EPITerminal. Look at EPITerminal’s properties and check that
the transaction property is set to a transaction that you can run on the
CICS server.
6. Create an EPIScreenButtons object. This is a simple set of buttons that you
can use to drive the terminal. Connect the EPIScreenButtons’
actionPerformed event to the EPIBasicScreenHandler’s actionPerformed
method. Depending on the tool you are using, check that the event data is
passed to EPIBasicScreenHandler.
7. You should now be able to connect to CICS and run a transaction. The
EPIBasicScreenHandler displays data sent from CICS and accepts user
input. When you select one of the buttons, the screen is sent back to CICS.
The screen is also sent if you select Enter while a text field has the input
focus. Make sure you disconnect the terminal when you have finished
with it.
Generating screen handler beans: You can automatically generate screen handler
beans, from BMS definition files. See “Screen Handler beans”. These screen
handler beans define bound properties for each labelled field in the
corresponding BMS map so that you can easily map between data from CICS
and user interface components.
To use the generated screen handlers you connect them to the EPITerminal’s
handleScreen event as above. Any number of screen handlers can be
connected to an EPITerminal. When the screen handler receives a new screen
from CICS, it decides whether the screen is displaying the corresponding BMS
map. If it recognizes the screen, it sends the screenHandled event. It also
updates its bound properties with the new data from CICS.
Screen Handler beans
A screen handler bean is a Java class that can:
v Recognize a CICS screen
v Make information from the screen available as bean properties
v Exit the screen
Screen handlers can be used with the EPI beans to create Java front-ends to
existing CICS 3270 applications. They are also used by the CICS Transaction
106 CICS Transaction Gateway: Programming Guide

Gateway Terminal Servlet both to exit transactions and to allow fields on the
screen to be accessed by symbolic names.
You do not have to write screen handler classes—they can be generated
automatically from BMS map definitions.
Generating screen handler beans: To generate screen handler classes, you
use the BMS Map Conversion utility supplied with the CICS Transaction
Gateway. For example, to generate beans for the screens defined by the BMS
map file called test1.bms, you use the command:
java com.ibm.ctg.epi.BMSMapConvert -b test1.bms
The parameters you can supply to the BMS Map Conversion tool are (in any
order):
-b to generate screen handler beans. The default is not to generate beans.
-k exit to set the key that the screen handler will use to exit the screen, for
example, -k clear. The default is PF3.
-p package name
to generate the Java source code with the statement package package
name, for example -p testing.beans. The default is not to add a
package statement.
BMS map definition filenames
Use your platform’s standard filename conventions. Files are assumed
to have the filetype .BMS if you do not give the full filename.
The BMS Map Conversion tool generates two Java source files for
each map defined in a BMS file:
v A Map class
v A ScreenHandler class
The names of the source files are derived from the map name, for
example, if a map called MAP1 is defined in the BMS file, then Java
source files called MAP1Map.java and MAP1ScreenHandler.java
would be produced.
The ScreenHandler class uses the Map class, so keep these files together.
EPI beans
Customizing and writing Screen Handlers: Customize the generated
ScreenHandler classes if:
v The screen handler cannot exit the screen it is associated with simply by
sending an AID, such as PF3, to CICS. In this case, you will need to change
the exitScreen method to do whatever is appropriate.
Chapter 7. Programming in Java 107

EPI beans
v You want to change the way the screen handler recognizes the screen it is
associated with. Normally, it checks that the screen contains the same fields
that were defined by the BMS map.
If you want to write your own screen handlers, consider the following points:
v They must be Java beans. In general, this means they should have a
constructor that takes no arguments, and they should implement the
java.io.Serializable interface.
v Generated screen handlers extend the class ScreenHandler. This is not
necessary; in fact for use with the EPI beans, screen handlers need only
provide a method that accepts a TerminalEvent parameter.
For use with the Terminal Servlet, screen handlers should implement the
TerminalEventListener interface and should use the TerminalEvent
isHandled method to signal that they have recognized a screen.
EPITerminal bean reference
This bean acts as a 3270 terminal connected to the CICS server through the
CICS Transaction Gateway.
To use this bean:
v Set the bean properties to appropriate values—you need at least to set the
URL of the CICS Transaction Gateway.
v Connect screen handler beans to the terminal handleScreen event.
v Call the connect method to make the terminal connect to CICS.
v Start a transaction by setting the transaction property to the transaction ID
then calling startTran.
v Make sure that the terminal is disconnected before your application ends,
by calling disconnect or terminate.
Properties:
Gateway URL
The URL of the CICS Transaction Gateway to connect to, for example:
setting the URL to: tcp://buster:2006 would result in the terminal
trying to connect to a CICS Transaction Gateway at the TCP/IP
address buster and the port number 2006.
Gateway Server Security class
The server security class that is used by the CICS Transaction
Gateway. Only advanced users should modify this property.
Standard terminal properties
Changing any of these values while the terminal is connected to the
server has no effect. You must disconnect and reconnect the terminal
to use different settings.
108 CICS Transaction Gateway: Programming Guide

EPI beans
These are the standard terminal properties:
v CICS Server Name—the CICS server to connect to
v Terminal Model Definition
v Terminal Netname
v Purge on Disconnect—set to true to force a purge rather than a
standard disconnect.
Extended terminal properties
Changing any of these values (apart from userid and password) while
the terminal is connected to the server has no effect. You must
disconnect and reconnect the terminal to use different settings.
These are the extended terminal properties:
v Signon Capability — choose either a signon capable or signon
incapable terminal. The CICS server must support the chosen
option.
v Read Timeout—Valid range 0—3600
v Install Timeout—Vaild range 0—3600
v Java encoding—The encoding to use for 3270 datastreams
v Userid—A Userid to be associated with the terminal
v Password—A Password to be associated with the terminal
ATI enabled
Set this property to true if you want to allow the CICS server to start
transactions on the terminal.
transaction
A transaction ID. This is the transaction that is started when the
method startTran is called.
transactionData
Transaction parameters. When startTran is called this string is passed
as a parameter to the transaction, for example: if the transaction ID is
CESN and the transaction data is set to USERID=fred PS=pswd then the
effect of calling startTran would be the same as typing CESN
USERID=fred PS=pswd at a CICS terminal.
AutoDisconnectTimeout
The terminal timeout interval in milliseconds. If the terminal is idle
(no data received from CICS) for longer than this period, the terminal
attempts to disconnect from CICS. You can set this value to 0 if you
do not want the terminal to time out. You should ensure that this
timeout value is less than the CICS Transaction Gateway connection
timeout value, otherwise the terminal may lose its connection to the
Gateway without being able to disconnect from CICS.
Chapter 7. Programming in Java 109

EPI beans
connected
This boolean value is set to true if the terminal is connected to CICS.
Events:
TerminalEvent
terminalConnected
when the terminal has connected to CICS.
terminalDisconnected
when the terminal has disconnected from CICS.
handleScreen
when the terminal receives a screen from CICS.
exceptionOccurred
if an exception occurs.
Methods:
connect()
Connects the terminal to the server, if not already connected.
startTran()
Starts a transaction on the terminal using the transaction ID and
transaction data already set.
send() Sends the current screen to CICS.
disconnect()
Disconnects the terminal from the server. The terminal cannot
disconnect from the server while a transaction is running. If a
transaction is running the terminal attempts to end it before
disconnecting. The terminal remains connected to the CICS
Transaction Gateway until the terminate method is called or the
application ends.
terminate()
Waits for the terminal to finish disconnecting, then closes the
connection to the CICS Transaction Gateway.
actionPerformed( ActionEvent e )
Sets the transaction ID to the event’s action command, then calls the
startTran method. Can be used to make a button push (or other
ActionEvent) trigger the starting of a transaction.
connect(int installTimeout)
Connects the terminal to CICS if not already connected. If the terminal
does not connect within the specified timeout, an exceptionOccurred
event is raised.
110 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
Security
EPI beans
getTermid()
Returns the current termId for a connected terminal
getUserid()
Returns the userid associated with the terminal
getPassword()
Returns the password associated with the terminal
setUserid()
Sets the Userid for the terminal. If it is a signon capable terminal then
this userid is used for the next transaction started.
setPassword()
Sets the Password for the terminal. If it is a signon capable terminal
then this password is used for the next transaction started.
verifyPassword()
If your CICS Server supports Password Expiry Management, this
verifies the current userid and password associated with the terminal.
It returns an EPISecurityAttrs Instance.
changePassword(String newPassword)
If your CICS Server supports Password Expiry Management, this
changes the password associated with the terminal and at the CICS
Server. It returns an EPISecurityAttrs Instance.
Send(String tranid, String tranData)
Starts the provided transaction on the CICS Server, passing up the
optional tranData.
CICS Transaction Gateway security classes
CICS Transaction Gateway provides the following classes for implementing
security:
com.ibm.ctg.security.JSSEServerSecurity
Use this interface to allow the exposure of of X.509 Client Certificates
when using the JSSE protocol.
Refer to your JSSE, or Java, documentation for information on using
X.509 certificates.
com.ibm.ctg.security.SSLightServerSecurity
Use this interface to allow the exposure of of SSL Client Certificates
when using the SSLight protocol.
com.ibm.ctg.security.SystemSSLServerSecurity
Use this interface to allow the exposure of of SSL Client Certificates
when using the System SSL protocol.
Chapter 7. Programming in Java 111

|
|
|
|
Security
com.ibm.ctg.security.ServerSecurity
Use this interface for server-side security classes that do not require
the exposure of SSL Client Certificates.
com.ibm.ctg.security.ClientSecurity
Use this interface for all client-side-side security classes.
com.ibm.ctg.util.RACFUserid
This class tries to map an X.509 Client Certificate to a RACF userid.
The certificate must already be associated with a valid RACF userid.
The SSLightServerSecurity, SystemSSLServerSecurity, JSSEServerSecurity,
or ServerSecurity interfaces and partner ClientSecurity interface define a
simple yet flexible model for providing security when using CICS Transaction
Gateway. Implementations of the interfaces can be as simple, or as robust, as
necessary; from simple XOR (eXclusive-OR) scrambling to use of the Java
Cryptography Architecture.
The SSLightServerSecurity, SystemSSLServerSecurity, and JSSEServerSecurity
interfaces have been designed to work in conjunction with the Secure Sockets
Layer (SSL) protocol. The interfaces allow server-side security objects access to
a Client Certificate passed during the initial SSL handshake. The exposure of
the Client Certificate depends on the the CICS Transaction Gateway being
configured to support Client Authentication.
An individual JavaGateway instance has an instance of a ClientSecurity class
associated with it, until the JavaGateway is closed. Similarly, an instance of
the partner SSLightServerSecurity, SystemSSLServerSecurity,
JSSEServerSecurity, or ServerSecurity class is associated with the connected
Java client, until the connection is closed.
The basic model consists of:
v An initial handshake to exchange pertinent information. For example, this
handshake could involve the exchange of public keys. However, at the
interface level, the flow consists of a simple byte-array, therefore an
implementation has complete control over the contents of its handshake
flows.
v The relevant ClientSecurity instance being called to encode outbound
requests, and decode inbound replies.
v The partner SSLightServerSecurity, SystemSSLServerSecurity,
JSSEServerSecurity, or ServerSecurity instance, being called to decode
inbound requests and to encode outbound replies.
The inbound request, and Client Certificate, is exposed via the
afterDecode() method:
– For SSLight, the afterDecode() method exposes the GatewayRequest
object, along with the com.ibm.sslight.SSLCert[] certificate chain object.
112 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
– For System SSL, the afterDecode() method exposes the GatewayRequest
object, along with the com.ibm.gskssl.SSLCertificate certificate object.
– For JSSE, the afterDecode() method exposes the GatewayRequest object,
along with the javax.security.cert.X509Certificate[] certificate chain
object.
ClientSecurity and SSLLightServerSecurity, SystemSSLServerSecurity,
JSSEServerSecurity, or ServerSecurity class instances should maintain as data
members sufficient information from the initial handshake to correctly encode
and decode the flows. At the server, each connected client has its own
instance of the ServerSecurity implementation class.
Using a Java 2 Security Manager
Java 2 provides a Security Manager system that controls access to Java
resources. It restricts access to Java resources by using a security policy.
Examples of protected resources are: reading a file, and opening a network
socket. When a program tries to access a protected resource, the Java Security
Manager verifies that both the code trying to access the resource, and,
possibly, the caller of that code, have appropriate permissions. Without these
permissions, the program cannot run.
If you are using any of the CICS Transaction Gateway Java APIs under a Java
2 security environment (such as a J2EE server), your application needs Java
permissions to execute correctly. The only exception to this is if you are using
the J2EE APIs in a managed environment.
Figure 18 shows the minimum permissions that your application needs to use
Gateway Java APIs. It might need additional permissions to execute correctly.
permission java.net.SocketPermission "*", "resolve, connect";
permission java.util.PropertyPermission "*", "read, write";
permission java.io.FilePermission "${user.home}${file.separator}ibm${file.separator}ctg${file.separator}-",
"read,write,delete";
permission java.lang.RuntimePermission "loadLibrary.*";
permission java.lang.RuntimePermission "shutdownHooks";
permission java.lang.RuntimePermission "modifyThread";
permission java.lang.RuntimePermission "modifyThreadGroup";
permission java.lang.RuntimePermission "readFileDescriptor";
permission java.lang.RuntimePermission "writeFileDescriptor";
permission java.security.SecurityPermission "putProviderProperty.IBMJSSE";
permission java.security.SecurityPermission "insertProvider.IBMJSSE";
Figure 18. Required Java 2 Security Manager permissions
Security
Permissions to access to the file system
Depending on the functions performed by your program, the CICS
Transaction Gateway Java APIs might require access to the file system. The
following permission
Chapter 7. Programming in Java 113

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Security
permission java.io.FilePermission "${user.home}${file.separator}ibm
${file.separator}ctg${file.separator}-","read,write,delete";
gives a general location for CICS Transaction Gateway classes to access the file
system.
The format is of the permission not mandatory, and you can specify
alternative locations or none at all. CICS Transaction Gateway classes require
access to the file system in the following cases:
v For writing trace information to a file
v For accessing KeyStores, if you are using JSSE for your SSL protocol
implementation
See Network security, intheCICS Transaction Gateway: Administration book
for your operating system, for information on how JSSE is selected as the
implementation.
|
For example, on Windows, you can specify the permission:
permission java.io.FilePermission "c:${file.separator}ibm${file.separator}ctg${file.separator}-",
"read,write,delete";
to allow access to the directory c:\ibm\ctg and all subdirectories.
Or, for example, on UNIX, you can specify the permission:
permission java.io.FilePermission "${file.separator}tmp${file.separator}ibm${file.separator}ctg${file.separator}-",
"read,write,delete";
to allow access to the directory /tmp/ibm/ctg and all subdirectories.
114 CICS Transaction Gateway: Programming Guide

Chapter 8. Programming using J2EE
The Common Client Interface
One of the main advantages of the J2EE resource adapter architecture is the
Common Client Interface (CCI). The CCI provides a standard interface that
allows developers to communicate with any number of Enterprise Information
Systems (EISs) through their specific resource adapters, using a generic
programming style. The CCI is closely modeled on the client interface used by
Java Database Connectivity (JDBC ), and is similar in its idea of Connections
and Interactions.
Within the CCI there are two distinct types of class: framework, and
input/output.
Framework classes
The framework is used to request a connection to an EIS such as
CICS, and execute commands upon that EIS passing input and
retrieving output. Examples include Connection and
ConnectionFactory.
Input/output classes
The input/output classes are used to pass any J2EE component
specific information both to the framework and the EIS. Examples are
InteractionSpec and ConnectionSpec.
CCI Framework Classes
The aim of the framework classes is to provide a connection to an EIS for
J2EE components to send and receive data. The first class you will use in
developing a J2EE Component is the ConnectionFactory object, which is used
to get a Connection object for the particular EIS you want to access. The
Connection object is then used to create one or more Interaction objects. You
execute commands on the EIS through these Interaction objects. Figure 19
shows an example of executing a command on an EIS using the J2EE CCI
interfaces.
ConnectionFactory cf =
Connection conn = cf.getConnection();
Interaction int = conn.createInteraction();
int.execute();
int.close();
conn.close();
Figure 19. A run through the Framework connector classes
© Copyright IBM Corp. 2002 115

CCI Framework Classes
Figure 20 shows how closely this matches up to the JDBC programming
model where database connections are used to create statement objects that
are in turn used to execute SQL queries on a database.
Connection conn =
Statement stmt = conn.createStatement();
String query = "SELECT * FROM A;";
stmt.executeQuery(query);
stmt.close();
conn.close();
Figure 20. The JDBC Connection model
CCI Input and Output classes
Using the framework classes discussed above gives a generic way of accessing
an EIS via a J2EE resource adapter. Because every EIS has different input and
output needs, the CCI interfaces provide a way for J2EE Components to pass
EIS-specific information to a J2EE resource adapter. The following types of
object are used for this purpose within a J2EE resource adapter:
v InteractionSpec objects
v ConnectionSpec objects
v Record objects
Spec objects define the action that a resource adapter will carry out, for
example the name of the program to execute on CICS. Record objects simply
store the input/output data to be used during the interaction, for example a
byte array representing an ECI COMMAREA.
Figure 21 on page 117 shows a complete run through of an interaction with an
EIS including input and output Record objects and Spec objects being used to
define the specific attributes of both the interaction and connection. As you
can see, setters are used to define any component-specific properties on the
Spec objects before they are used, thus allowing a developer to customize the
behavior of a resource adapter. The following sections cover the ECI and EPI
implementations of these classes in detail, including properties that can be set
on the Spec objects, and supported Record types.
116 CICS Transaction Gateway: Programming Guide

ConnectionFactory cf =
ECIConnectionSpec cs = new ECIConnectionSpec();
cs.setXXX(); //Set any connection specific properties
Connection conn = cf.getConnection( cs );
Interaction int = conn.createInteraction();
ECIInteractionSpec is = new ECIInteractionSpec();
is.setXXX(); //Set any interaction specific properties
RecordImpl in = new RecordImpl();
RecordImpl out = new RecordImpl();
int.execute( is, in, out );
int.close();
conn.close();
Figure 21. Complete CCI run through.
CCI Input and Output classes
Connector specification API Javadoc
You can obtain the connector architecture API Javadoc from the Sun Web site,
this will assist in the coding of your CCI applications and provides
information such as the exceptions used by CCI implementations.
J2EE Connector Specification API
IBM recommends that you get the J2EE Connector Specification document from
Sun’s Web site at java.sun.com/j2ee/download.html, to help in coding your
CCI applications. It contains information such as the exceptions used in CCI
apllications.
ECI resource adapter CCI
The ECI resource adapter allows a J2EE developer to access CICS programs,
using data areas known as COMMAREAs to pass information to and from the
server. This means that you can now use the large installed base of proven
applications on CICS within your J2EE Components. The CCI interfaces for
CICS are in the com.ibm.connector2.cics package.
ECI connection interfaces
The ECI resource adapter provides implementations of the connection
interfaces. Use the ECIConnectionSpec class implementation directly. Use the
ConnectionFactory and Connection interfaces, rather than the ECI-specific
implementations. These classes allow connections to a CICS Server using ECI.
ECIConnectionSpec: This class allows the J2EE component to pass security
credentials different from those defined at deployment time. You can set the
credentials using the ECIConnectionSpec constructor, or with setters on a
newly constructed ECIConnectionSpec. See “Security credentials and the CICS
Chapter 8. Programming using J2EE 117

ECI resource adapter CCI
resource adapters” on page 129 for information on the precedence of security
credentials. Properties supported include:
UserName The userid to be used to access CICS.
Password The password for the userid.
So to obtain a connection you code something like this:
ConnectionFactory cf =
ECIConnectionSpec cs = new ECIConnectionSpec();
cs.setUserName("myuser");
cs.setPassword("mypass");
Connection conn = cf.getConnection(cs);
ECI interaction interfaces
The ECI resource adapter also provides implementations of the interaction
interfaces. Use the ECIInteractionSpec class implementation directly. Use the
Interaction interface, rather than the ECI-specific implementation.
ECIInteractionSpec: This class defines the specific properties of a call to
CICS and is required as a parameter to each call to ECIInteraction.execute().
The properties defined on ECIInteractionSpec are:
InteractionVerb
The ECI resource adapter supports both synchronous and
asynchronous calls to CICS. Use this property to specify which is to
be used for this interaction. Available choices are:
v SYNC_SEND - An asynchronous call.
v SYNC_RECEIVE - A synchronous receive. This is used to retrieve a
reply from a SYNC_SEND call.
v SYNC_SEND_RECEIVE - A synchronous call.
Notes:
1. When a SYNC_SEND call has been issued with the execute()
method of a particular ECIInteraction object, that instance of
ECIInteraction cannot execute another SYNC_SEND, or
SYNC_SEND_RECEIVE, until a SYNC_RECEIVE has been
executed.
2. Simultaneous asynchronous calls to the same managed connection
are permitted, provided this does not result in two asynchronous
calls being outstanding within the same transaction. An exception
is thrown if this happens.
FunctionName
When SYNC_SEND or SYNC_SEND_RECEIVE is specified in the
InteractionVerb property, FunctionName needs to contain the name of
the program to execute on CICS.
118 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
|
|
|
ECI resource adapter CCI
ExecuteTimeout
This property holds the timeout value for interactions with CICS.
Possible values include:
0 No timeout. This is the default value.
A positive integer
Time in milliseconds.
ExecuteTimeout is not used on the z/OS operating system.
CommareaLength
The length of the COMMAREA being passed to CICS inside your
input record. If this is not supplied a default is used:
SYNC_SEND, SYNC_SEND_RECEIVE
Length of input record data
SYNC_RECEIVE
The value of ReplyLength
ReplyLength
The amount of data you want back from CICS. This can reduce
network bandwidth if the data returned by CICS is less than the
entire COMMAREA, and you know the size of the data in advance.
You are recommended not to set ReplyLength, so that the CICS
Transaction Gateway can automatically strip trailing zeros from the
incoming COMMAREA, without needing to know its size in advance.
Your program will still receive a full COMMAREA of the size
specified in commareaLength; only the amount of data sent over the
network is reduced.
Automatic stripping of trailing zeros is not performed if you set
ReplyLength. For more information on COMMAREA stripping, see
the ECIRequest class in JavaDoc.
As with ECIConnectionSpec, you can set properties on the ECIInteractionSpec
class at either construction time or using setters. Unlike ECIConnectionSpec,
the ECIInteractionSpec class has been designed as a Java bean. So in a
managed environment, your server may provide tools to allow you to define
these properties using a GUI without writing any code.
ECI resource adapter input/output records using the streamable interface
For input and output the ECI resource adapter supports only records that
implement the javax.resource.cci.Streamable interface. This allows the ECI
resource adapter to read and write streams of bytes that make up the CICS
COMMAREAs directly to and from the Record objects supplied to the
execute() method of ECIInteraction. Figure 22 on page 120 shows how to build
Chapter 8. Programming using J2EE 119

ECI resource adapter CCI
a record for use as input by the ECI resource adapter using the method
supplied in the javax.resource.cci.Streamable interface.
Byte commarea[] = new byte[10];
ByteArrayInputStream stream = new ByteArrayInputStream(commarea);
Record in = new RecordImpl();
in.read(stream);
int.execute(..., in, ...);
Figure 22. Using the streamable interface to build an input record
To retrieve a byte array from the output record the reverse of the process
shown in Figure 22 can be achieved by using the output records write()
method using a ByteArrayOutputStream object as the parameter. The streams
toByteArray() method will then provide the CICS COMMAREA output in the
form of a byte array. In Figure 22 a class called RecordImpl is used as the
concrete implementation class of the javax.resource.cci.Record interface. To
provide more functionality for your specific J2EE components, you can write
implementations of the Record interface that allow you to set the contents of
the record using the constructor. This avoids the use of the
ByteArrayInputStream in Figure 22. A managed environment may provide
tools that allow you to build implementations of the Record interface that are
customized for your J2EE components needs without writing any code.
Application transaction demarcation
In a managed environment transactions can be controlled by the server, or by
the application itself. In a nonmanaged environment transactions have to be
controlled by the application. This section discusses how to achieve this for
local transactions.
When carrying out multiple interactions with CICS using a deployed resource
adapter you may wish to group all actions together to ensure that they either
all succeed or all fail. You can use the LocalTransaction interface to do this.
The ECI resource adapter provides an implementation of this interface. You
do not work directly with this implementation; instead you use the interface.
For example:
120 CICS Transaction Gateway: Programming Guide

Connection conn = null;
Interaction int = null;
try {
conn =(Connection)cf.getConnection();
int = conn.createInteraction();
ECIInteractionSpec spec = new ECIInteractionSpec(SYNC_SEND_RECEIVE, "EC01");
LocalTransaction tran = conn.getLocalTransaction();
tran.begin();
int.execute(spec, in, out);
...
int.execute(spec, in, out);
tran.commit();
}
catch( ResourceException re ) {
tran.rollback();
}
try {
int.close();
conn.close();
}
catch( ResourceException re ) {
...
}
Figure 23. Determining whether to commit or rollback
Once you have completed all the work in your transaction your J2EE
component can commit the transaction if it was successful, or roll back if an
error occurred and the final result is undesired. Figure 23 shows a possible
method for determining whether to call commit() or rollback(). If an error
occurs during a commit() call, the ECI resource adapter automatically tries to
rollback the transaction on CICS, as no other action is valid once a transaction
has failed to commit.
Samples
J2EE ECI sample programs are provided in the \samples
subdirectory. Refer to the samples.txt file, in that subdirectory, for more
information.
EPI resource adapter CCI
The CICS EPI resource adapter allows a J2EE component to communicate
with CICS EPI transactions that use 3270 datastreams for input and output.
The way the resource adapter achieves this is to represent a 3270 terminal
with each EPIConnection object, thus providing access to the CICS 3270
interface. The CCI interfaces for CICS are in the com.ibm.connector2.cics
package.
Note: ATIs are not supported.
ECI resource adapter CCI
Chapter 8. Programming using J2EE 121

|
|
|
|
|
|
|
|
EPI resource adapter CCI
EPI connection interfaces
The EPI resource adapter provides implementations of the connection
interfaces. Use the EPIConnectionSpec class implementation directly. Use the
ConnectionFactory and Connection interfaces, rather than the EPI-specific
implementations. These classes allow connections to a CICS Server using EPI.
EPIConnectionSpec: This allows the J2EE component to pass security
credentials different to those defined at deployment time. You can set the
credentials using the EPIConnectionSpec constructor, or with setters on a
newly constructed EPIConnectionSpec. See “Security credentials and the CICS
resource adapters” on page 129 for information on the precedence of security
credentials. Properties supported include:
UserName The userid to be used to access CICS.
Password The password for the userid.
NetName The netname for the terminal to be used by
this connection as defined within CICS.
DeviceType The device type of the terminal that the
EPIConnection will use.
Using this class allows different components to use the same resource adapter
while still using different terminals and user accounts on the CICS server.
EPI interaction interfaces
The EPI resource adapter also provides implementations of the interaction
interfaces. Use the EPIInteractionSpec class implementation directly. Use the
Interaction interface, rather than the EPI-specific implementation.
EPIInteractionSpec: The EPIInteractionSpec class allows a J2EE component
to define the properties of a particular interaction. Like the ECI resource
adapter, an EPIInteractionSpec instance must be supplied to each call of
EPIInteraction.execute(). The properties defined on EPIInteractionSpec are:
InteractionVerb
The EPI resource adapter supports synchronous calls to CICS.
Available choices are:
v SYNC_SEND - A synchronous call. It does not unblock until the EPI
transaction has sent all the information that would appear on a
screen.
v SYNC_RECEIVE - A synchronous receive. Used to retrieve the
current contents of the screen.
v SYNC_SEND_RECEIVE - A synchronous call.
122 CICS Transaction Gateway: Programming Guide

EPI resource adapter CCI
FunctionName
When SYNC_SEND or SYNC_SEND_RECEIVE is specified in the
InteractionVerb property, FunctionName needs to contain the name of
the program to execute on CICS.
AID This value holds the AID key that will be sent to CICS. The default
value is enter.
CursorRow
The row on which the cursor will be positioned on the terminal
screen.
CursorColumn
The column in which the cursor will be positioned on the terminal
screen.
OutputAttributeType
This allows you to control what will be held in the attribute byte for
the field on a returned screen. It applies only to the streamable
interface (see “Writing input and output records” on page 124).
Available options are:
ATTRIBUTE_NONE
The value 0x20 is stored in the byte which represents the
attribute byte on the screen
ATTRIBUTE_BASE
(Default) Stores the base attribute in the byte which represents
the attribute byte on the screen
ATTRIBUTE_FOREGROUNDCOLOR
Stores the foreground color value in the byte which represents
the attribute byte on the screen
ATTRIBUTE_BACKGROUNDCOLOR
Stores the background color value in the byte which
represents the attribute byte on the screen
ATTRIBUTE_HIGHLIGHT
Stores the highlight attribute value in the byte which
represents the attribute byte on the screen
ATTRIBUTE_TRANSPARENCY
Stores the transparency attribute value in the byte which
represents the attribute byte on the screen
ATTRIBUTE_MARKER
Stores the byte defined by the enumeration MARKER_BYTE
value in the byte which represents the attribute byte on the
screen. This can be used to locate fields easily within an
output record using the streamable interface.
Chapter 8. Programming using J2EE 123

|
|
|
EPI resource adapter CCI
So for example if you want to know the foreground color of a field
you set the OutputAttributeType to
ATTRIBUTE_FOREGROUNDCOLOR and then read the attribute file
out of the byte stream contained in your output record. To see
whether the same field has the highlight attribute set you execute
another SYNC_RECEIVE interaction with the OutputAttributeType
property set to ATTRIBUTE_HIGHLIGHT.
In addition to these input properties the EPIInteractionSpec also has a set of
output properties for use by the J2EE component:
CursorRow
The current row on which the cursor is positioned.
CursorColumn
The current column in which the cursor is positioned.
ScreenWidth
The width of the current screen.
ScreenDepth
The depth of the current screen.
TermId
The ID of the terminal being used for the interaction, as defined in
CICS.
MapName
The name of the BMS map being used on the current screen.
MapSetName
The name of the mapset that the current map belongs to.
Closing an EPIInteraction
Closing an EPIInteraction does not affect the state of the connection; the
terminal remains connected.
Writing input and output records
Records are needed to supply information to the EPI resource adapter and to
retrieve information from the resource adapter. Although the EPI resource
adapter supports the Streamable interface as defined in the Connector
Architecture, if you wish to use it you must write your own records, parsing
the input stream and generating the output stream correctly. For information
about the Stream format see “Stream Format” on page 127.
The EPI resource adapter provides a more efficient way to access information
in the form of a record that is ready to use. This is the recommended way to
access and send information to a resource adapter.
124 CICS Transaction Gateway: Programming Guide

EPI Screen Record: The EPI resource adapter provides a record that you can
use with the EPI resource adapter to retrieve and send information to CICS
through EPI. Like the EPI Support classes, it represents information by
containing field objects within a screen object. Use the Screen container to get
a reference to a field, and then use methods on the field to query and
manipulate the field text.
The record is found in the com.ibm.connector2.cics package. It is an
implementation of the screenable interface, which is the contact between the
EPI resource adapter and the record on how to transfer information.
EPIScreenRecord: To create an EPIScreenRecord:
EPIScreenRecord screen = new EPIScreenRecordImpl();
Note that you actually instantiate an instance of EPIScreenRecordImpl.
You then pass this as an output record initially and start a new transaction,
for example:
EPIInteractionSpec epiSpec = new EPIInteractionSpec();
epiSpec.setFunctionName(“CESN”);
epiSpec.setAID(AIDKey.enter);
epiSpec.setInteractionVerb(EPIInteractionSpec.SYNC_SEND_RECEIVE);
// epiInter is an interaction created elsewhere
epiInter.execute(epiSpec, null, screen);
Note the use of null as the input record.
The screen information is in the screen object. Other screen information such
as cursor position is returned to your defined EPIInteractionSpec object. You
can then request a specific field by index number, which has a range from 1 to
the total number of fields on the screen, or you can request an iterator over all
the fields. The fields are indexed in order starting from the top left of the
screen going from left to right to the bottom right of the screen. The iterator
returns each field in incrementing index order.
So for example you can obtain a field using the index number by coding:
EPIFieldRecord field = screen.getField(7);
To use the iterator, code the following:
java.util.Iterator it = screen.getFields();
while (it.hasNext()) {
EPIFieldRecord field = (EPIFieldRecord)it.next();
....
....
}
EPI resource adapter CCI
Chapter 8. Programming using J2EE 125

EPI resource adapter CCI
The following is a code example of a function that takes a screen record and
prints out the screen in a layout suitable for a terminal:
public void printScreen(EPIScreenRecord inscr) {
int col = 1;
int row = 1;
}
System.out.println(“——————————————————————————————————————”);
for (int i = 1; i row) {
System.out.print(“\n”);
row++;
col = 1;
}
while (f.getTextCol() > col) {
System.out.print(“ ”);
col++;
}
if (f.isDisplay()) {
System.out.print(f.getText());
col += f.getText().length();
}
}
catch (ScreenException se) {
}
}
System.out.print(“\n”);
System.out.println(“——————————————————————————————————————”);
After you have accessed and updated the fields, pass the record back as the
input record. If you wish, you can use it again as the output record. For
example:
epiSpec.setAID(AIDKey.enter);
epiInter.execute(epiSpec, screen, screen);
EPIFieldRecord: You always access EPIFieldRecords from an
EPIScreenRecord instance (rather than creating them direct). The
EPIFieldRecord has many methods to access the various attributes of a field
(for example, whether it is protected or not, which colors are applicable). You
can also retrieve and modify text. See CICS Transaction Gateway: Programming
Reference, for more information on these interfaces in the
com.ibm.connector2.cics package. EPIFieldRecord contains various static final
variables that define names for color attributes, highlighting and transparency.
126 CICS Transaction Gateway: Programming Guide

EPI resource adapter CCI
ScreenException: An EPIScreenRecord and EPIFieldRecord can throw
exceptions. They are checked exceptions, and all inherit from the base class
ScreenException. See CICS Transaction Gateway: Programming Reference, for
more information on these exceptions.
Stream Format: The stream is a byte representation of the screen. The
number of bytes that are sent to the application, and received from the
application, should be the same as the number of bytes on the screen. That is,
the number of bytes should equal the product of screen depth and screen width.
For example, if the terminal to which you are connected has a 24 by 80
character screen the number of bytes that should be flowed to and from the
resource adapter is: 24x80 = 1920 bytes.
When providing an input record, you must flow the exact number of bytes on
the stream otherwise the record will be rejected. Also, the byte stream must
represent exactly what the screen looks like as seen by the resource adapter. If
it does not the record will be rejected.
For each field on the screen, there is a byte preceeding the field that
represents the attribute byte on a 3270 terminal. On a 3270 screen this byte is
displayed as a blank. However, in the byte stream it can be controlled to
contain information about the field. You can select what is placed in this field
by specifying an appropriate value in the EPIInteractionSpec
setOutputAttributeType method. For example, this byte could contain a
blank, which is the base attribute, or it could contain a value which represents
the color attribute for that field. See“EPIInteractionSpec” on page 122 for more
details.
A special option is EPIInteractionSpec.ATTRIBUTE_MARKER. This will store the
value EPIInteractionSpec.MARKER_BYTE in that location. This enables a record
to dynamically locate a field, without needing prior knowledge of the screen
format, for example a BMS map.
Writing LogonLogoff classes
LogonLogoff classes are specified at deployment and used to logon to signon
capable terminals, or to terminals that install as signon unknown.
It is recommended that you use signon incapable terminals, in which case you
do not need the LogonLogoff classes.
If you choose to use the classes, implement the
com.ibm.connector2.cci.LogonLogoff interface which has the following
interface definition:
Chapter 8. Programming using J2EE 127

EPI resource adapter CCI
public interface LogonLogoff {
public void logoff(javax.resource.cci.Connection conn);
public void logon(javax.resource.cci.Connection conn,
javax.security.auth.Subject security);
}
This class is only required for the EPI resource adapter. Also, you do not need
to implement the logoff method because this is never called. However, you
must provide a dummy implementation so that the class can be compiled. As
you can see with the logon method signature, you are passed a connection
and a security subject. The logon is driven in the same way as for applications
that communicate with CICS using the EPI resource adapter. You create
interactions using this connection and, when finished, you close the
interaction. For example:
Interaction epiInt = (Interaction)(conn.createInteraction());
EPIInteractionSpec spec = new EPIInteractionSpec();
//------------------------------------------------------------------
// configure the spec to perform a CESN, and execute the call
//-----------------------------------------------------------------spec.setAID(AIDKey.enter);
spec.setFunctionName("CESN");
spec.setInteractionVerb(EPIInteractionSpec.SYNC_SEND_RECEIVE);
EPIScreenRecord screen = new EPIScreenRecordImpl();
epiInt.execute(spec,null,screen);
Close the interaction when you have finished with it. For example:
epiInt.close();
Note: Do not close the connection within the LogonLogoff class.
The credentials with which you logon are held as Subject object. To retrieve
this information you need to get an iterator from the private credentials. There
is a single entry within the private credentials of type PasswordCredential. You
can obtain the userid and password from this entry as follows:
Iterator it = security.getPrivateCredentials().iterator();
PasswordCredential pc = null;
if (it.hasNext()) {
pc = (PasswordCredential)it.next();
}
if (pc == null) {
throw new javax.resource.spi.SecurityException("
Unable to logon, No Security Information Provided");
}
String user = pc.getUserName();
String pass = new String(pc.getPassword());
If there are any problems, throw an appropriate
javax.resource.spi.SecurityException.
128 CICS Transaction Gateway: Programming Guide

Java security: You might need to grant your LogonLogoff class the Java
security permission, to enable it to retrieve the credential information from the
subject passed to it:
Samples
J2EE EPI sample programs are provided in the samples subdirectory of your
CICS Transaction Gateway installation. These are documented in the
samples.txt file, which is also found at that location.
Security credentials and the CICS resource adapters
EPI resource adapter CCI
permission javax.security.auth.PrivateCredentialPermission "javax.resource.spi.security.PasswordCredential * \"*\"", "read";
Security Credentials for accessing CICS can come from three different places.
These are the ConnectionSpec properties, the deployed security credentials, or
the server itself (for nonmanaged environments, the third option does not
apply). The precedence for these credentials is:
1. The Server Supplied Credentials (highest precedence)
2. The ConnectionSpec Supplied Credentials
3. The Deployed Security Credentials.
Compiling applications
To compile supplied applications in both managed and nonmanaged
environments, include the following in the CLASSPATH:
v cicsj2ee.jar (required for access to Connection and Interaction Specs)
v ctgclient.jar (required for AIDkey objects)
v ccf2.jar (required for creating LogonLogoff classes)
v connector.jar (required for all resource adapter applications)
v screenable.jar (required if using the EPI Screen Record)
Compiling and running Enterprise Bean clients and deploying Enterprise
Beans
If you develop an Enterprise Bean that passes back the EPI Screen Record as a
return parameter, your deployment tool needs the following jar files:
v cicsj2ee.jar
v screenable.jar
An Enterprise Bean client that receives an EPI Screen Record also needs these
jar files on the classpath.
Chapter 8. Programming using J2EE 129

Using the J2EE CICS resource adapters in a nonmanaged environment
Using the J2EE CICS resource adapters in a nonmanaged environment
You can use the resource adapters in a nonmanaged environment. In this
environment, you are responsible for:
v Defining the EIS connection
v Creating the ConnectionFactory object
v Providing your own connection pooling
v Supplying your log writer
v Managing transactions
Your nonmanaged environment can be either inside, or outside, a J2EE server
environment. The resource adapters provide a default connection manager to
support execution within the nonmanaged environment.
Transaction management applies only to the ECI resource adapter. See
“Application transaction demarcation” on page 120 for information on
managing transactions in a nonmanaged environment.
Creating the appropriate ConnectionFactory object
Your application needs to get an appropriate ConnectionFactory object. In the
managed environment, the server or application does this for you, and you
can reference it using JNDI (see “Storing ConnectionFactory objects” on
page 131). In the nonmanaged environment, unless you have previously
registered one that you can access, you must create a ConnectionFactory
object with the appropriate EIS connection information.
Creating an ECI ConnectionFactory
You must first create an ECIManagedConnectionFactory and set the
appropriate properties on this object. The properties are the same as the
deployment parameters described in J2EE setup and configuration, intheCICS
Transaction Gateway: Administration book for your operating system. These are
accessible using setter and getter methods. The J2EE Programming Reference
documentation lists the setter and getter methods for the
ECIManagedConnectionFactory and shows the relationship between
deployment parameters and properties. The following example shows how to
create a ConnectionFactory for ECI:
ECIManagedConnectionFactory eciMgdCf = new ECIManagedConnectionFactory();
eciMgdCf.setConnectionURL("local:");
eciMgdCf.setPortNumber(new Integer(0));
eciMgdCf.setServerName("tp600");
eciMgdCf.setLogWriter(new java.io.PrintWriter(System.err));
eciMgdCf.setUserName("myUser");
eciMgdCf.setPassword("myPass");
eciMgdCf.setTraceLevel(new
Integer(ECIManagedConnectionFactory.RAS_TRACE_ENTRY_EXIT));
ConnectionFactory cxf = (ConnectionFactory)eciMgdCf.createConnectionFactory();
130 CICS Transaction Gateway: Programming Guide

Creating the appropriate ConnectionFactory object
Creating an EPI ConnectionFactory
You must first create an EPIManagedConnectionFactory and set the
appopriate properties on this object. The properties are the same as the
deployment parameters described in J2EE setup and configuration, intheCICS
Transaction Gateway: Administration book for your operating system. This
process is similar to that for creating an ECI ConnectionFactory. The following
example shows how to create a ConnectionFactory for EPI:
EPIManagedConnectionFactory epiMgdCf = new EPIManagedConnectionFactory();
epiMgdCf.setConnectionURL("local:");
epiMgdCf.setPortNumber(new Integer(0));
epiMgdCf.setServerName("tp600");
epiMgdCf.setLogWriter(new java.io.PrintWriter(System.err));
epiMgdCf.setUserName("myUser");
epiMgdCf.setPassword("myPass");
epiMgdCf.setSignonType(new Integer(0)); // signon capable terminal
epiMgdCf.setLogonLogoffClass("com.acme.companyApp.ourCICSLogon");
epiMgdCf.setTraceLevel(new
Integer(EPIManagedConnectionFactory.RAS_TRACE_ERROR_EXCEPTION));
ConnectionFactory cxf = (ConnectionFactory)epiMgdCf.createConnectionFactory();
Storing ConnectionFactory objects
You can store ConnectionFactory objects for later reuse, so that your
application doesn’t need to rebuild them. Inside a J2EE server environment,
IBM recommends that you register your ConnectionFactory object, which has
links to your EIS connection information, in the J2EE Java Naming and
Directory Interface (JNDI ) service. This makes migration from nonmanaged
to managed Java environments easier because applications can get
ConnectionFactory objects in the same manner. However, this may not be
possible outside a JNDI environment unless either an LDAP server, or an
appropriate JNDI Service Provider, is available within your environment.
The resource adapter ConnectionFactory objects support both the serializable
and referenceable Java interfaces. This means that you can choose how to
register them in the JNDI. For more information, refer to the J2EE Connector
Architecture Specification.
If you plan to use serializable interfaces, refer to J2EE Tracing, intheCICS
Transaction Gateway: Administration book for your operating system. This gives
information on how serialization and deserialization of ConnectionFactory
objects affects the setting of the LogWriter property.
Running the J2EE CICS resource adapters in a nonmanaged environment
In a J2EE environment, all of the required Java libraries should be available.
You might need to ensure that your J2EE server adds the following delivered
jar files to your CLASSPATH. These files are in the \classes
subdirectory:
v cicsj2ee.jar
v ctgclient.jar
Chapter 8. Programming using J2EE 131

Running the J2EE CICS resource adapters in a nonmanaged environment
v ctgserver.jar (required only for local: protocol)
v ccf2.jar
v connector.jar
v screenable.jar (required for the EPIScreenRecord)
Outside a J2EE enviroment, you must ensure that, as well as the above
libraries being listed in the CLASSPATH, the following Java extensions are
also available:
v JAAS (required for EPI resource adapter)
v JTA (required for the ECI resource adapter)
JAAS is included with IBM JREs and JDKs by default. The JTA library is
available from the Sun Java website.
All of the above libraries and extensions should be available from the J2EE
server libraries.
J2EE Tracing
In a nonmanaged environment where the DefaultConnectionManager is used
the application can set the LogWriter property on the class to define where
trace messages are sent. It is important to note however that in a nonmanaged
environment, if the ConnectionFactory is serialized for storage the LogWriter
must be set after deserialization in order for it to be used, as it is not restored
automatically after deserialization. Figure 24 shows an example of this
process.
ECIManagedConnectionFactory MCF = new ECIManagedConnectionFactory();
MCF.setLogWriter(myLogWriter);
ECIConnectionFactory cf = MCF.createConnectionFactory();
objOutStream.write(cf);
ECIConnectionFactory cf2 = (ECIConnectionFactory) objInStream.read();
DefaultConnectionManager.setLogWriter(myLogWriter);
Figure 24. An example of resetting the LogWriter after ConnectionFactory deserialization.
Issues with tracing if ConnectionFactory serialized
As described above, if you use the serializable interface to store your
ConnectionFactory then you lose the reference to your LogWriter. This is
because LogWriters are not serializable and cannot be stored. When you
deserialize your ConnectionFactory it will not contain a reference to the
132 CICS Transaction Gateway: Programming Guide

Running the J2EE CICS resource adapters in a nonmanaged environment
LogWriter. To ensure that your LogWriters are stored on any connections
created from this ConnectionFactory you must do the following. This only
applies in a nonmanaged environment.
DefaultConnectionManager.setLogWriter(new java.io.PrintWriter(System.err));
Connection Conn = (Connection)cxf.getConnection();
The setLogWriter method on the DefaultConnectionManager, which is
supplied with the resource adapters, is a static method. The example above
shows how to set the log to output the System.err. The trace level applied to
the ManagedConnectionFactory remains.
Resource adapter samples
The samples consist of one ECI and one EPI Sample. They show how to use
the CICS resource adapters as well as demonstrating how to write custom
records that implement the javax.resource.cci.Streamable interface. For
information on how to deploy the ECI and EPI resource adapters, see J2EE
setup and configuration, intheCICS Transaction Gateway: Administration book for
your operating system.
ECI sample
The ECI Sample consists of a stateless Enterprise Bean, a client application,
and a custom record that demonstrates using the Streamable interface. The
following files are part of the ECI Sample:
ECIDateTime.java Enterprise Bean Remote Interface
ECIDateTimeHome.java Enterprise Bean Home Interface
ECIDateTimeBean.java Enterprise Bean Implementation
ECIDateTimeClient.java Enterprise Bean client program
JavaStringRecord.java Custom Record
Ejb-jar-eci-1.1.xml Example of a deployment descriptor
The deployment descriptor is an example of an EJB 1.1–compliant deployment
descriptor for this Enterprise Bean. If you wish to package it up into a jar file,
rename it to Ejb-jar.xml and store it in the META-INF directory of the jar
file. It may require further entries if it is to be deployed into an EJB
2.0–compliant environment.
See your J2EE Server documentation for information on how to compile and
deploy the bean. The Enterprise Bean looks for an ECI connection factory
named java:comp/env/ECI. The bean must refer to this resource when
deployed. Refer to your J2EE Server documentation on how to deploy the
resource adapter with an entry in the JNDI with this name. The client
Chapter 8. Programming using J2EE 133

ECI sample
program looks for the ECIDateTime bean with a name of ECIDateTimeBean1.
See your J2EE Server document for details of how to setup the bean with this
JNDI name.
You will need to install the sever sample program EC01 on your CICS Server.
This file can be found in the samples\server subdirectory of your CICS
Transaction Gateway installation. Further details of this sample can be found
in thesamples.txt file in the samples folder.
The bean is a simple bean that outputs the date and time as known to the
CICS Server, and can be deployed as Bean Managed Transaction. The Custom
record takes a COMMAREA and converts it to a string. Ensure that the EC01
sample program, which you installed on your CICS server, sends its results in
ASCII, as the COMMAREA is expected in ASCII. The JavaStringRecord does
however allow for the selection of other encodings, and is commented using
JavaDoc. The Client program takes no parameters.
EPI sample
The EPI Sample consists of
v A Stateful Enterprise Bean
v An Enterprise Bean Client
v A custom record which demonstrates using the Streamable interface
v A sample LogonLogoff class
The following files are part of the EPI Sample:
EPIPlayScript.java Enterprise Bean Remote Interface
EPIPlayScriptHome.java Enterprise Bean Home Interface
EPIPlayScriptBean.java Enterprise Bean Implementation
EPIPlayScriptClient.java Enterprise Bean client program
CICSCESNLogon.java A LogonLogoff Class
Ejb-jar-epi-1.1.xml Example of a deployment descriptor
The deployment descriptor is an example of an EJB 1.1-compliant deployment
descriptor for this Enterprise Bean. If you wish to package it up into a jar file,
rename it to Ejb-jar.xml and store it in the META-INF directory of the jar
file. It may require further entries if it is to be deployed into an EJB
2.0-compliant environment.
Your J2EE Server documentation describes how to compile and deploy the
bean within your environment. However, you need to ensure that he
following jar files are also available on the CLASSPATH:
v cicsj2ee.jar
134 CICS Transaction Gateway: Programming Guide

v connector.jar
v ctgclient.jar
v ccf2.jar
The Enterprise Bean looks for an EPI connection factory named
java:comp/env/EPI. See your J2EE Server’s documentation for details of how
deploy the resource adapter under this reference in the JNDI. When deploying
the bean into your environment you need to supply this reference for the bean
to find the resource. The client program looks for the EPIPlayScript bean with
a name of EPIPlayScript1. Refer to your J2EE Server documentation for
details of how to setup the bean with this name in the JNDI namespace. The
bean can be deployed as a Bean Managed Transaction.
The bean is designed to take a series of commands and drive a 3270
interaction. Once the commands are complete, the field text is returned as a
string array based on fields requested to be returned by the script. The client
can then look at these field texts and send more commands to drive that
interaction if necessary. The commands that drive the 3270 screen are as
follows:
S(txn) Start transaction “txn”
F(x)=“Text” Set field number x to “Text”. Field numbers
start at 1.
P(aid) Press key ’aid’
C(row, col) place cursor at row, col (row and col start at 1)
R(x) Adds the text of the field at the given field
number to the string array that will be
returned. Field numbers start at 1.
So an example of a script might be:
S(CESN)F(7)="myuser"F(10)="mypass"P(enter)R(1)
EPI sample
The EPIPlayScriptClient program takes no parameters; it has a default
command sequence coded into it. Experiment by changing this command
sequence or enhancing the sample.
The CICSCESNLogon.java sample contains example code on how to logon to a
CICS 390 system. There are also examples showing how to logon to CICS for
NT 3.1 and CICS for OS/2 in comments. They are designed to work for
English systems and may have to be tailored for other versions of CICS and
languages. In order to use this class, deploy it as part of the sample bean and
reference it when you deploy the EPI resource adapter. For more information
Chapter 8. Programming using J2EE 135

EPI sample
about how to deploy the EPI resource adapter see J2EE setup and configuration,
in the CICS Transaction Gateway: Administration book for your operating
system.
136 CICS Transaction Gateway: Programming Guide

Chapter 9. Programming in COM
Establishing the working environment
You are provided with Component Object Model (COM) Object Oriented (OO)
support for the Client daemon in the Windows environment. This includes the
COM runtimes, type libraries, the BMS map utility, and sample code.
The COM libraries
The COM libraries are automation compatible. Automation compatible means
that they can be used easily from programming languages such as Visual
Basic, VBScript and Delphi. However, these libraries are only supported with
Visual Basic and VBScript and full support is not provided for other
development environments.
Servers
The libraries are provided as in-process servers (cclieci.dll and
ccliepi.dll) and out-of-process or local servers (ccloeci.exe and
ccloepi.exe). Although local servers are provided they are not supported and
have not been tested in a DCOM environment.
It is recommended that you use in-process servers as they provide better
performance than the out-of-process servers.
Registration
The COM libraries are registered at installation time. This registers the COM
classes, associated ProgIDs and the type libraries for each of the libraries. At
this time you must choose whether you require in or out of process servers.
Visual Basic will only use the type libraries if you register them to each Visual
Basic Project. It is recommended that you do this to make full use of the the
features and performance enhancements of these type libraries. See “Enabling
the use of the COM libraries” on page 138 for details about project
enablement.
VBScript does not use type libraries.
All the COM libraries support automatic registration and de-registration . If
you have de-registered the COM libraries the sections “Registering in-process
servers” and “Registering out-of-process servers” on page 138 describe how to
reregister them.
Registering in-process servers: To register in-process servers use the
Microsoft supplied program REGSVR32.
© Copyright IBM Corp. 2002 137

Establishing the working environment
For example to register the ECI COM libraries issue the command
REGSVR32 CCLIECI.DLL
to de-register issue the command
REGSVR32 /U CCLIECI.DLL
Registering out-of-process servers: To register the out-of-process servers, run
the executable and, when a window appears indicating that registration has
been done, close it. For example to register the EPI libraries run the program
CCLOEPI.
To unregister the out-of-process servers, run the executable with the
/unregister parameter. For example to unregister the EPI libraries run the
program
CCLOEPI /unregister
Enabling the use of the COM libraries
To set up Visual Basic to use the type libraries, go to the Visual Basic
Project/References... dialog and select either
Client daemon EPI
or
Client daemon ECI
depending on your application needs. Press OK.
If the type libraries are not listed then the COM libraries probably have not
been registered. Refer to the previous section for information on registering
the COM libraries.
COM Libraries: Objects and Apartments
The design of the Client daemon COM Libraries requires the passing of a
COM object to another COM object. For this to work the relevant COM
objects need to be created in the same apartment. For example, in ECI, to
make a link method call on the Connect COM object a Flow, Buffer and UOW
object need to be passed. These must all be created in the same apartment in
order to function properly.
Again with EPI it is important to ensure that the Terminal Session and Map
COM Objects are created in the same apartment. The Terminal is responsible
for creating the Screen object and it will create it in the same apartment as
itself. This Screen object is then responsible for creating field objects and also
creates them in the same apartment as itself. The out-of-process servers
guarantees that all objects are created in the same apartment. However, the
programmer has control of the apartment where COM objects are created
when they use the in-process servers.
138 CICS Transaction Gateway: Programming Guide

Establishing the working environment
In most cases in Visual Basic you do not need to worry about apartments as
you will be creating single threaded applications.
Using the COM classes
The Client daemon provides COM classes for the CICS ECI and EPI on
Windows. The interfaces could be used from any application development
environment that supports COM automation. However, this book refers only
to Visual Basic and VBScript. Only these environments are supported.
These COM classes can be accessed from Microsoft Visual Basic, from Visual
Basic for Applications (which is provided built-in to applications such as
Microsoft Excel version 5.0.), and from VBScript.
COM sample programs are provided in the \samples
subdirectory. Refer to the samples.txt file, in that subdirectory, for more
information.
Object Creation and Interfaces
To talk to COM objects you have to use interfaces. The ECI and EPI COM
libraries provide two interfaces per COM class.
The first interface is called IDispatch and is provided to support old Visual
Basic applications and VBScript. A second interface, a Custom interface, is also
provided for use by Visual Basic. This interface is faster than the IDispatch
interface and it is recommended that you use this interface with Visual Basic.
Each COM class provides an IDispatch interface and a Custom interface.
Visual Basic provides more than one way to create a COM object and select
the interface to talk to that object. To create an object there are the
CreateObject function and the New function. It is recommended that you use
the New function to create objects in Visual Basic.
VBScript is simpler. It provides only one way to create an object, the
CreateObject function, and you must use the IDispatch interface.
The following are some examples of creating COM objects
Set eci = CreateObject("Ccl.ECI")
Set eci = New CcloECI
Set connection = CreateObject("Ccl.Connect")
Set connection = New CcloConn
Note the two ways you can request the object class. When using CreateObject
you specify a string called the Programmatic ID or ProgID for short. When
using the New function you specify the Class name that is registered in the
type library.
Chapter 9. Programming in COM 139

COM classes
When using Visual Basic you have the choice of which interface you want to
use. If you DIM your variable as Object, then you select the IDispatch
interface. If you DIM your variable as the Class name then you will select the
custom interface. To create a terminal object in Visual Basic you would use the
code:
Dim Terminal as CclOTerminal
Set Terminal = New CclOTerminal
Figure 25. Creating a terminal object in Visual Basic
or you can combine the above into a single statement if you wish
Dim Terminal as New CclOTerminal
When using VBScript, VBScript will automatically select the IDispatch
interface for you. For example to create a terminal Object in VBScript you
would use the code
Dim Terminal
Set Terminal = CreateObject("Ccl.Terminal")
Figure 26. Creating a terminal Object in VBScript
It is recommended that you:
v choose one interface type or the other.
v do not mix the object interface types in your program. This type of
environment is not supported.
v select the custom interface because it should provide performance
improvements.
No matter which interface you select or how the object is created, you use the
objects identically in your program.
Type Libraries and Visual Basic Intellisense
Type libraries add many useful features to the COM libraries. One of these is
Visual Basic Intellisense. The type libraries provide Visual Basic with
information so that it can help you with code completion. It prompts you
with the format of the method and, where applicable, constants which might
be relevant to method parameters or return values you can test for. For
example if you create a terminal object for Visual Basic as shown in Figure 25,
when you want to select a method on the terminal object, press the ’.’ key and
you are presented with a list of available methods. Select the method and
press space or open bracket and you are shown the required parameters. You
can also browse the type libraries for reference information on the ECI and
EPI classes by using the Visual Basic Object Browser. Select either CclECILib
140 CICS Transaction Gateway: Programming Guide

COM classes
for ECI classes reference or CclEPILib for EPI classes reference information.
The type libraries are embedded within the in-process library files
cclieci.dll and ccliepi.dll.
Class summary
The following table lists the COM classes that the CICS COM servers provide.
Details of the methods these provide are in CICS Transaction Gateway:
Programming Reference.
Table 7. ECI COM classes
COM class Description
Buffer Buffer used for passing data to and from a CICS server
Connection Controls a connection to a CICS server
ECI Provides access to a list of CICS servers configured in the
Client daemon
Flow Controls a single interaction with CICS server program
SecAttr Provides information about security attributes (passwords)
SecTime Provides date and time information
UOW Coordinates a recoverable set of calls to a CICS server
Table 8. EPI COM classes
COM class Description
EPI Initializes and terminates the CICS EPI and provides access to
a list of CICS servers configured in the Client daemon
Field Provides access to a single 3270 field on a screen.
Map Provides access to 3270 fields defined by a CICS server BMS
map
Screen Provides access to a 3270 terminal screen
Session Controls a sequence of 3270 terminal interactions with a CICS
server
Terminal Controls a 3270 terminal connection
Samples illustrating the use of the ECI and EPI COM classes from Visual Basic
are supplied in the \samples\vb subdirectory. The following
sections show extracts from the samples.
Exception Handling
With the ECI and EPI classes there appear to be two ways to check for
problems when invoking methods.
Chapter 9. Programming in COM 141

COM classes
One way could be to use the ErrorWindow method and set it to false, then
check the ExCode and ExCodeText methods after a call to see what the return
codes are. This is not the recommended way to do it and only exists now to
support backward compatibility for old applications.
The recommended way is to use the Err objects which Visual Basic and
VBScript provide. An Err object contains the information about an error.
Visual Basic supports On Error Goto and On Error Resume features to detect
that an error has occurred. VBScript only supports the On Error Resume Next
feature. If you use On Error Resume Next either in Visual Basic or VBScript,
you must always enter this line before any COM object call that you expect
could return an error. Visual Basic/VBScript might not reset the Err variable
unless you do this.
The type of interface you have selected (you DIM’ed a variable as either
Object or classname) will affect the value contained in the Err.number
property. It is possible to write a generic routine that handles all values in
Err.Number and converts them to the documented ExCode error codes
available. The example code following shows how to achieve this.
To get full advantage of this technique, ensure that you get full information in
the Err object. Issue the following call after creating the ECI or EPI object:
ECI.SetErrorFormat 1
or, for EPI:
EPI.SetErrorFormat 1
Figure 27 on page 143 shows how to handle errors in Visual Basic.
142 CICS Transaction Gateway: Programming Guide

Private Sub Command1_Click()
’
’ The following code assumes you have created the
’ required objects first, ECI, Connect, Flow, UOW,
’ Buffer
’
On Error GoTo ErrorHandler
conn.Link flow, "EC01", buf, uow
Exit Sub
ErrorHandler:
’
’ Ok, the Connect call failed
’ Parse the Error Number, this will work regardless of
’ how the ECI objects were Dimmed
’
Dim RealError As CclECIExceptionCodes
RealError = (Err.Number And 65535) - eci.ErrorOffset
If RealError = cclTransaction Then
’
’ Transaction abend, so query the Abend code
’
AbendCode = flow.AbendCode
If AbendCode = "AEY7" Then
MsgBox "Invalid Userid/Password to execute CICS Program", , "CICS ECI Error"
Else
MsgBox "Unable to execute EC01, transaction abend:" + AbendCode, , "CICS ECI Error"
End If
Else
MsgBox Err.Description, , "CICS ECI Error"
End If
End Sub
Figure 27. Visual Basic exception handling sample
Figure 28 on page 144 shows error handling code for VBScript.
COM classes
Chapter 9. Programming in COM 143

COM classes
On Error Resume Next
con.Link flow, "EC01", buf, uow
if Err.Number 0 then
’
’ Ok, the Connect call failed
’ Parse the Error Number, this will work regardless of
’ how the ECI objects were Dimmed
’
RealError = Err.Number And 65535 - eci.ErrorOffset
’
’ 13 = CclTransaction, a transaction abend.
’
If RealError = 13 Then
’
’ Transaction abend, so query the Abend code
’
AbendCode = flow.AbendCode
If AbendCode = "AEY7" Then
Wscript.Echo "Invalid Userid/Password to execute CICS Program"
Else
Wscript.Echo "Unable to execute EC01, transaction abend:", AbendCode
End If
Else
Wscript.Echo Err.Description
End If
End If
Figure 28. VBScript exception handling sample
Known Issues with Migration
As discussed in Exception Handling, the values in the Err.Number will vary
depending on which interface and Error Format you selected. If an old
application used DIM to define the variables as their class name, and checked
Err.Number for the value of 8600 (other values were not available in previous
releases), this check will fail.
Making an ECI link call to CICS using Visual Basic
The first step is to declare object variables for the ECI interfaces to be used.
See the COM chapter of CICS Transaction Gateway: Programming Reference for
details of the available interfaces. Declarations are usually made in the
General Declarations section of a Visual Basic program:
Dim ECI As CclOECI
Dim Connect As CclOConn
Dim Flow As CclOFlow
Dim Buffer As CclOBuf
Dim UOW As CclOUOW
144 CICS Transaction Gateway: Programming Guide

The required ECI objects are then instantiated using the Visual Basic New
function. This can be done in the Form_Load subroutine or at some later stage
in response to some user action. Note that a CclOECI object must be created
first.
Sub ECILink_Click()
Set ECI = New CclOECI
Set Connect = New CclOConn
Set Flow = New CclOFlow
Set Buffer = New CclOBuf
Details of the CICS server to be used – server name (as configured in the
Gateway initialization file) , userid and password – are supplied via the
Details method on the Connect object. The Buffer object is initialized with
some data to be sent to CICS:
Connect.Details "CICSNAME", "sysad", "sysad"
Buffer.SetString "Hello"
Now we are ready to make the call to CICS. The Link method takes as
parameters the Flow object, the name of the CICS server program to be
invoked, the Buffer object and a UOW object. In this example a null variable
is supplied for the UOW parameter, so this call will not be part of a
recoverable Unit Of Work. The contents of the Buffer returned from CICS are
output to a Visual Basic text box “Text1”:
Connect.Link Flow, "ECIWTO", Buffer, UOW
Text1.Text = Buffer.String
Finally the CICS COM objects are deleted:
Set Connect = Nothing
Set Flow = Nothing
Set Buffer = Nothing
End Sub
Guide to COM CICS ECI
This example sends and receives a simple text string. In practice, the Buffer
object would contain more complex data (for example C data structure). For
binary data the Buffer.SetData and Buffer.Data methods are provided to
allow the contents to be accessed as a Byte array.
A typical client application could access CICS through one or more
Connect.Link calls and construct a ’business object’ for use in end-user Basic
programs. One approach to this would be to implement the ’business object’
as a separate COM automation server containing the logic to process the
contents of the CclOBuffer objects.
Chapter 9. Programming in COM 145

Guide to COM CICS ECI
Making an ECI link call to CICS using VBScript
This is similar to the previous section visual basic but the creating of the
objects is different.
It is not necessary to DIM any variables with VBScript but it would be good
programming practice to do so.
Dim ECI, Connect, Flow, Buffer, UOW
To create the objects you use the code:
Set ECI = CreateObject("Ccl.ECI")
Set Connect = CreateObject("Ccl.Connect")
Set Flow = CreateObject("Ccl.Flow")
Set Buffer = CreateObject("Ccl.Buffer")
Set UOW = Nothing
If you are not going to use a UOW, you must explicitly set it to ’Nothing’ in
VBScript.
ECI Call Synchronization Types
The Client daemon ECI COM classes support synchronous (“blocking”) and
deferred synchronous (“polling”) protocols. These classes do not support the
asynchronous calls that are available in the C++ classes.
In the previous example a Flow object was used with the default
synchronization type of cclSync. When this Flow object was used as the first
parameter on Connect.Link, a synchronous link call was made to CICS. The
Visual Basic program was then blocked until the reply was received from
CICS. When the link call returned the reply from CICS was immediately
available in the Buffer object.
To make a deferred synchronous call you use the SetSyncType method on the
Flow object to set the Flow to cclDSync. When this Flow object is used on a
Connect.Link call, the ECI call is made to CICS, but control returns
immediately to the Visual Basic Program, and the reply from CICS must be
retrieved later using the Poll method on the Flow object:
Sub ECIDsync_Click()
Set Connect = New CclOConn
Set Flow = New CclOFlow
Set Buffer = New CclOBuf
Connect.Details "CICSNAME", "sysad", "sysad"
Flow.SetSyncType cclDSync
Buffer.SetString "Hello"
Connect.Link Flow, "ECIWTO", Buffer, UOW
End Sub
146 CICS Transaction Gateway: Programming Guide

The call to CICS is now in progress. At a later stage (in response to a user
action, or perhaps when the Visual Basic program has completed some other
task) the Poll method is used on the Flow object to collect the reply from
CICS. Note that the Poll method requires a Buffer object as parameter if reply
data is expected from CICS
Sub ECIReply_Click()
If Flow.Poll(Buffer) Then
Text1.Text = Buffer.String
Else
Text1.Text = "No reply from CICS yet"
End If
End Sub
CICS Server Information and Connection Status
The ECI COM class provides the names and descriptions of CICS servers
configured in the Gateway initialization file. The Connect COM class provides
methods for querying the availability of a particular CICS server.
Object variables are declared as before, this time we use ECI, Connect and
Flow COM classes:
’Declare object variables
Dim ECI As CclOECI
Dim Connect As CclOConn
Dim Flow As CclOFlow
On user request, the objects are created, and a list of CICS server names and
their descriptions is constructed:
Sub ECIServers_Click()
Dim I as Integer
’Instantiate CICS ECI objects
Set ECI = New CclOECI
Set Connect = New CclOConn
Set Flow = New CclOFlow
’List CICS server information
For I = 1 To ECI.ServerCount
List1.AddItem ECI.ServerName(I)
List1.AddItem ECI.ServerDesc(I)
Next
End Sub
Guide to COM CICS ECI
A synchronous status call to the first server is made, and the results of the call
displayed in a text field:
Chapter 9. Programming in COM 147

Guide to COM CICS ECI
Connect.Details ECI.ServerName(1)
Connect.Status Flow
Text1.Text = Connect.ServerStatusText
ECI Link Calls within a Unit Of Work
Using the UOW COM class, a number of link calls can be made to a CICS
server within a single Unit of Work. Updates to recoverable resources in the
CICS server can then be committed or backed out by the client program as
necessary.
In this example a UOW object is created, and is used as a parameter to the
Connect.Link calls:
Sub ECIStartUOW_Click()
’Instantiate CICS ECI objects
Set Connect = New CclOConn
Set Flow = New CclOFlow
Set UOW = New CclOUOW
Set Buffer = New CclOBuf
Connect.Details "CICSNAME", "sysad", "sysad"
End Sub
Sub ECILink_Click()
’Set up the commarea buffer
Buffer.SetString Text1.Text
Buffer.SetLength 80
’Make the link call as part of a Unit of Work
Connect.link Flow, "ECITSQ", Buffer, UOW
End Sub
After a number of link calls have been made, the Commit or Backout
methods on the Ccl UOW interface can be used:
Sub Commit_Click()
’Commit the CICS updates
UOW.Commit Flow
End Sub
Sub Backout_Click()
’Backout the CICS updates
UOW.Backout Flow
End Sub
If no UOW object is used (a NULL value is supplied on the Connect.Link
call), each link call becomes a complete unit of work (equivalent to LINK
SYNCONRETURN in the CICS server).
148 CICS Transaction Gateway: Programming Guide

When you use Logical units of work, you must ensure that you backout or
commit active units of work, this is particularly important at program
termination. You can check if a logical unit of work is still active by checking
the uowId method for a non-zero value.
In Visual Basic, if you Dim a UOW variable but never create the object, it is
assumed to a be of value Nothing and the Link call will therefore not
associate a unit of work with the call. In VBScript, however, it is necessary to
ensure explicitly that the variable is set to nothing. To do this code
Set UOW=Nothing
before making your link call.
Handling COMAREAS in VB
A CommArea is a block of storage that contains all the information you send
to and receive from the server. Because of this, you must create a CommArea
that is big enough for this information. For example, you might need to send
a 12 byte serial number to the server, but receive a maximum of 20 Kb back
from the server; this means you must create a Commarea of size 20 Kb. To do
this you could code
Set Buf = new CclOBuf ’ create extensible buffer object
Buf.SetString(serialNo)
Buf.setLength(20480) ’ stores Nulls in the unused area
Guide to COM CICS ECI
In the above example, Commarea is given the serial number and the buffer is
increased to the required amount, but the extra area is filled with nulls. This
is important as it ensures that the information transmitted to the server is
kept to a minimum. The Client daemon strips off the excess nulls and only
transmits the 12 bytes to the server.
ECI Userid and Password Management
You can perform security management on servers that support Password
Expiry Management. Refer to the CICS Transaction Gateway: Administration
book for your operating system, for more information on supported servers
and protocols.
To use these features you must first create a connection object and invoke the
Details method to associate a userid and password with the object. The two
methods available are VerifyPassword that checks the userid and password
within the connection object with the Server Security System, and
ChangePassword that allows you to change the password at the server. If
successful the connection object password is updated accordingly.
If either call is successful, you are returned a CclOSecAttr object. This object
provides access to information such as last verified time, expiry time and last
access time. If, for example, you query the last verified time, you are returned
Chapter 9. Programming in COM 149

Guide to COM CICS ECI
a CclOSecTime object and you may use the SecTime COM class methods to
obtain the information in various formats. The following code shows the use
of these various objects.
’ Connection object already created called conn
on error goto pemhandler
Dim SecAttr as CclOSecAttr
Dim LastVerified as CclOSecTime
Dim lvdate as Date
Set SecAttr = conn.VerifySecurity
Set LastVerified = SecAttr.LastVerifiedTime
lvdate = LastVerified.GetDate
strout = Format(lvdate, "hh:mm:ss, dddd, mmm d yyyy")
Text1.Text = strout
exit sub
pemhandler:
’ handle a expired password here maybe
end sub
Connection to CICS 3270 applications using Visual Basic
Note: The COM classes do not contain any specific support for 3270
datastreams that contain DBCS fields. However they do not support
3270 datastreams that contain mixed SBCS and DBCS fields.
The first step is to declare object variables for the EPI interfaces to be used,
usually in the General Declarations section of a Visual Basic program:
Dim EPI As CclOEPI
Dim Terminal As CclOTerminal
Dim Session As CclOSession
Dim Screen As CclOScreen
Dim Field As CclOField
The required EPI objects are then instantiated using the Visual Basic New
function. This can be done in the Form_Load subroutine or at a later stage in
response to a user action.
The CclOEPI object must be created first to initialize the Client daemon EPI. A
CclOTerminal object can then be created, and a connection established to a
specific CICS server using the Terminal.Connect method. The first parameter
to this method is the CICS server name (as configured in the Gateway
initialization file), the other parameters specify additional connection details.
150 CICS Transaction Gateway: Programming Guide

See CICS Transaction Gateway: Programming Reference for additional
information.
Sub EPIConnect_Click()
’Create Ccl.EPI first to initialize EPI
Set EPI = New CclOEPI
’Create a terminal object and connect to CICS
Set Terminal = New CclOTerminal
Terminal.Connect "CICSNAME","",""
’Create a session object (defaults to synchronous)
Set Session = New CclOSession
End Sub
Running a CICS 3270 session
Having connected a CclOTerminal object to the required CICS server the
Terminal, Session, Screen and Field COM classes are used to start a
transaction on CICS and navigate through 3270 panels, accessing 3270 fields
as required by the application.
The required CICS transaction is started using its four character transaction
code. Initial transaction data can also be supplied on the Terminal.Start
method, in this example no data is required. To access the 3270 data returned
by CICS, a screen object is obtained from the terminal object, and a variety of
methods can be used to obtain fields from the screen and read and update
text and attributes in the fields:
Sub EPIStart_Click()
’Start CESN transaction
Terminal.Start Session, "CESN", ""
’Get the screen object
Set Screen = Terminal.Screen
’Output the text from some 3270 fields
Set Field = Screen.FieldByIndex(5)
List1.AddItem Field.Text
Set Field = Screen.FieldByIndex(6)
List1.AddItem Field.Text
Guide to COM CICS EPI
The CESN transaction is waiting for input from the user, the program could
enter text into some fields and continue the transaction, in this example we
simply end the transaction by sending PF3 to CICS.
’Send PF3 back to CICS to end CESN
Screen.SetAID cclPF3
Terminal.Send Session
’Output the text from a 3270 field
Set Field = Screen.FieldByIndex(1)
List1.AddItem Field.Text
End Sub
Chapter 9. Programming in COM 151

Guide to COM CICS EPI
Lastly the terminal should be disconnected, and the EPI terminated. The order
in which this is done is very important.
Sub EPIDone_Click()
Term.Disconnect
’Delete the EPI COM objects
Set Field = Nothing
Set Screen = Nothing
Set Session = Nothing
Set Terminal = Nothing
Set EPI = Nothing
End Sub
EPI call synchronization types
The Client daemon EPI COM classes support synchronous (“blocking”) and
deferred synchronous (“polling”) protocols. The Visual Basic environment
does not support the asynchronous calls that are available in the C++ classes.
In the previous example a Session object was used with the default
synchronization type of cclSync. When this Session object was used as the first
parameter on Terminal.Start or Terminal.Send, a synchronous link call was
made to CICS. The Visual Basic program was then blocked until the reply was
received from CICS. When the call returned updated screen data from CICS
was immediately available in the Screen object.
To make a deferred synchronous call you use the Session.SetSyncType
method to set the Session to cclDSync. When this Session object is used on a
Terminal.Start or Terminal.Send call, the screen contents are transmitted to
CICS as 3270 datastream, but the method returns immediately. This allows the
Visual Basic program to continue other tasks, including user interactions,
while the CICS server transaction is running. Further 3270 screen updates
from CICS must be retrieved later using the Poll method on the Terminal
object:
Sub EPIDSync_Click()
’Create a session object (deferred synchronous)
Set Session = New CclOSession
Session.SetSyncType cclDSync
Terminal.Start Session, "CESN", ""
End Sub
The transaction is now in progress in the CICS server. At a later stage (in
response to a user action, or when the Visual Basic program has completed
some other task) the Terminal.PollForReply method is used to collect the
reply from CICS:
152 CICS Transaction Gateway: Programming Guide

Sub EPIReply_Click()
If terminal.State cclDiscon And terminal.State cclError Then
If terminal.PollForReply Then
’Screen has been updated, output some fields
Set Screen = Terminal.Screen
Set Field = Screen.FieldByIndex(1)
List1.AddItem Field.Text
Else
List1.AddItem "No Reply from CICS yet"
End If
End If
End Sub
A CICS server transaction may send more than one reply in response to a
Terminal.Start or Terminal.Send call. More than one Terminal.PollForReply
call may therefore be needed to collect all the replies. Use the Terminal.State
method to find out if further replies are expected. If there are, the value
returned will be cclServer.
CICS Server Information
The EPI COM class provides the names and descriptions of CICS servers
configured in the Gateway initialization file.
An EPI object is created as in the previous examples, and a list of CICS server
names and their descriptions is output to a listbox “List1”:
Sub EPIServers_Click()
Dim I
’Instantiate CICS EPI object
Set EPI = New CclOEPI
’List CICS server information
For I = 1 To EPI.ServerCount
List1.AddItem EPI.ServerName(I)
List1.AddItem EPI.ServerDesc(I)
Next
Guide to COM CICS EPI
Using BMS Map data with EPI COM classes
Many CICS server programs use Basic Mapping Support (BMS) to implement
their 3270 screen designs. The server programs can then use symbolic names
for the individual screen maps and for the 3270 fields on those maps. If the
BMS source files are available, they can be copied to the Client daemon
development environment and used in the implementation of a Visual Basic
EPI program.
The CICS BMS Conversion Utility (CICSBMSC.EXE) provided with the Client
daemon produces a Visual Basic definitions file (a .BAS file) from the source
BMS file (.BMS file). This definitions file can then be included in a Visual Basic
program, and the same symbolic names used to identify maps and their fields
in the server program can be used in the client program with the EPI Map
COM class.
Chapter 9. Programming in COM 153

Guide to COM CICS EPI
The /B option should be specified when running the conversion utility to
produce Visual Basic definitions:
CICSBMSC /B .BMS
Running the conversion utility on the BMS file for the supplied sample server
program EPIINQ (contained in the CICS Transaction Gateway samples
subdirectory) produces the following Visual Basic definitions:
Public Const MAPINQ = xx.xx.xx.xx.xx.xx.xx
Public Const MAPINQ1_PRODNAM = xx
Public Const MAPINQ1_APPLID = xx
Public Const MAPINQ1_TIME = xx
The first constant MAPINQ1 identifies the map and provides information
describing the position, size and layout of the map, remaining constants
define the named fields within the map.
The following example shows how to use the Map COM class to access fields
by their BMS symbolic names:
Dim EPI As CclOEPI
Dim Terminal As CclOTerminal
Dim Session As CclOSession
Dim Screen As CclOScreen
Dim Map as CclOMap
Dim Field As CclOField
First the EPI is initialized and a 3270 terminal connection to CICS is started as
in the earlier example:
Sub EPIConnect_Click()
’Create Ccl.EPI first to initialize EPI
Set EPI = New CclOEPI
’Create a terminal object and connect to CICS
Set Terminal = New CclOTerminal
Terminal.Connect "CICSNAME","",""
’Create a session object (defaults to synchronous)
Set Session = New CclOSession
End Sub
Then the BMS application is started. This example uses a transaction code
“EPIC” which runs the CICS supplied server program EPIINQ:
Sub EPIRunBMS_Click()
Terminal.Start Session, "EPIC", ""
Set Screen = Terminal.Screen
At this point the CICS server program has returned the first screen to the
client. This is expected to be a known map “MAPINQ1” so we create a Map
object, and use the Map.Validate method to initialize it and to verify that we
154 CICS Transaction Gateway: Programming Guide

eceived the expected 3270 screen. Fields can then be accessed using the
Map.FieldByName method:
Set Map = New CclOMap
If (Map.Validate(Screen,MAPINQ1)) Then
Set Field = Map.FieldByName(MAPINQ1_PRODNAM)
List1.AddItem Field.Text
Set Field = Map.FieldByName(MAPINQ1_TIME)
List1.AddItem Field.Text
Else
List1.Text= "Unexpected screen data"
End If
A more complex application would then enter data into selected fields, set the
required AID key (Enter, Clear, PF or PA key) and navigate through further
screens as required. The client application can mix the use of the Screen COM
class (and its FieldByIndex and FieldByPosition methods) with the use of the
Map COM class.
Connecting to CICS 3270 applications using VBScript
This is again very similar to Visual Basic but differs in how you create the
objects. You do not need to have to Dim your variables but it is good coding
practice to do so. As with Visual basic COM objects do not support DBCS
fields in the 3270 datastreams. To create objects you must use the
CreateObject function, for example:
Sub EPIConnect_Click()
’ Create Ccl.EPI first to initialise EPI
Set EPI = CreateObject("Ccl.EPI")
’ Create a terminal object and connect to CICS
Set Terminal = CreateObject("Ccl.Terminal")
Terminal.Connect "CICSNAME","",""
’ Create a session object (defaults to synchronous)
Set Session = CreateObject("Ccl.Session")
End Sub
In a similar manner, to create a Map object you issue
Set Map = CreateObject("Ccl.MAP")
Screen objects and Fields Objects are created for you.
Guide to COM CICS EPI
Support for Automatic Transaction Initiation (ATI)
The CICS server API call EXEC CICS START allows a server program to start
a transaction on a particular terminal. This mechanism, called Automatic
Transaction Initiation (ATI), requires additional programming at the client side
to handle the interaction between these transactions and normal
client-initiated transactions.
Chapter 9. Programming in COM 155

Guide to COM CICS EPI
Client applications can control whether ATI transactions are allowed by using
the setATI and queryATI methods on the Terminal COM class. The default
setting is for ATIs to be disabled. The following code fragment shows how to
enable ATIs for a particular terminal:
// Create terminal connection to CICS server
Dim terminal as CclOTerminal
Set terminal = new CclOTerminal
terminal.details "MYSERVER","",""
terminal.setATI CclATIEnabled
The Client daemon queues ATIs for a terminal while a transaction is in
progress. The Ccl Terminal class runs any outstanding ATIs as soon as a
transaction ends, and calls Additional programming needed to handle the ATI
replies, and to run ATIs before or between client-initiated transactions,
depending on the call synchronization type used:
Synchronous
When you call the Terminal send method, any outstanding ATIs are
run after the client-initiated transaction has completed. The Terminal
class waits for the ATI replies then updates the CclOScreen object
contents as part of the synchronous send call. If you expect an ATI to
occur before or between client-initiated transactions, call the Ccl
Terminal receiveATI method to wait synchronously for the ATI.
Deferred synchronous
After the CclTerminal Start or Send method is called for a deferred
synchronous session, the Poll or PollForReply method is used to
receive the replies. Outstanding ATIs are started when the last reply is
received (that is on the final Poll or PollForReply method). You can
also call the Poll or PollForReply method to start and receive replies
for ATIs between client-initiated transactions.
As the Poll or PollForReply methods can be called before or between
client-initiated transactions, the receiveATI method is not needed (and
is invalid) for deferred synchronous sessions.
Security Management
You can perform security management on servers that support Password
Expiry Management. Refer to the CICS Transaction Gateway: Administration
book for your operating system, for more information on supported servers
and protocols.
To use these features you first must have created a Terminal object and
invoked the SetTerminalDefinition method to associate a userid and
password with the object. The two methods available are VerifyPassword
which checks the userid and password within the terminal object with the
156 CICS Transaction Gateway: Programming Guide

Server Security System, and ChangePassword which allows you to change the
password at the server. If successful, the terminal object password is updated
accordingly.
If either call is successful, you are returned a CclOSecAttr object. This object
provides access to information such as last verified Date and Time, Expiry
Date and Time and Last access Date and Time. If you query for example last
verified Date, you are returned a CclOSecTime object which allows you to get
the information in various formats. The following shows the use of these
various objects.
’ Terminal object already created called term
on error goto pemhandler
dim SecAttr as CclOSecAttr
dim LastVerified as CclOSecTime
dim lvdate as Date
set SecAttr = term.VerifyPassword
set LastVerified = SecAttr.LastVerifiedTime
lvdate = LastVerified.GetDate
strout = Format(lvdate, "hh:mm:ss, dddd, mmm d yyyy")
Text1.Text = strout
exit sub
pemhandler:
’ handle a expired password here maybe
end sub
Guide to COM CICS EPI
Chapter 9. Programming in COM 157

Guide to COM CICS EPI
158 CICS Transaction Gateway: Programming Guide

Part 3. Appendixes
© Copyright IBM Corp. 2002 159

160 CICS Transaction Gateway: Programming Guide

Appendix A. ECI extensions that are environmentdependent
This Appendix describes extensions to the ECI that are supported in certain
environments.
The Appendix is organized as follows:
“Call type extensions”
“Time-outs” on page 11
“Fields to support ECI extensions” on page 163
“Reply message formats” on page 164
“ECI return notification” on page 164
“Summary of input parameter requirements” on page 164.
Call type extensions
The following call types are for asynchronous calls.
For more information about the program link calls, see Table 9 on page 164,
and ECI_ASYNC call type in the C and Cobol chapter of CICS Transaction
Gateway: Programming Reference.
For more information about the status information calls, see Table 9 on
page 164, and ECI_STATE_ASYNC call type in CICS Transaction Gateway:
Programming Reference.
Asynchronous program link call, with notification by message
(ECI_ASYNC_NOTIFY_MSG)
This call type is available only for programs running on Windows.
The calling application gets control back when the ECI accepts the request.
Note that this does not indicate that the program has started to run, merely
that the parameters have been validated. The request might be queued for
later processing.
The ECI sends a notification message to the specified window when the
response is available. (For details of the message format, see “Reply message
formats” on page 164.) On receipt of this notification, the calling application
should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the
actual response.
The following fields are required parameters for notification by message:
© Copyright IBM Corp. 2002 161

Environment-dependent extensions
v eci_async_notify.window_handle
v eci_message_id indicates the message type to be used in the notification
process.
eci_message_qualifier can be used as an input to provide a user-defined
name for the call. It is returned as part of the notification message for the
Windows environment.
Asynchronous program link call, with notification by semaphore
(ECI_ASYNC_NOTIFY_SEM)
This call type is available only for programs running on Windows.
The calling application gets control back when the ECI accepts the request.
Note that this does not indicate that the program has started to run, merely
that the parameters have been validated. The request might be queued for
later processing.
The ECI posts the specified semaphore when the response is available. On
receipt of this notification, the calling application should use ECI_GET_REPLY
or ECI_GET_SPECIFIC_REPLY to receive the actual response.
eci_message_qualifier can be used as an input to provide a user-defined
name for the call.
The following field is a required parameter for notification by semaphore:
v eci_async_notify.sem_handle refers to the semaphore.
Asynchronous status call, with notification by message
(ECI_STATE_ASYNC_MSG)
This call type is available only for programs running on Windows.
eci_message_qualifier can be used as an input to provide a user-defined
name for the call.
The ECI sends a notification message to the specified window when the
response is available. (For details of the message format, see “Reply message
formats” on page 164.) On receipt of this notification, the calling application
should use ECI_GET_REPLY or ECI_GET_SPECIFIC_REPLY to receive the
actual response.
For details of the additional parameters relating to notification by message,
see the description of the ECI_ASYNC_NOTIFY_MSG call type.
Asynchronous status call, with notification by semaphore
(ECI_STATE_ASYNC_SEM)
This call type is available only for programs running on Windows.
162 CICS Transaction Gateway: Programming Guide

eci_message_qualifier can be used as an input to provide a user-defined
name for the call.
The ECI posts the specified semaphore when the response is available. On
receipt of this notification, the calling application should use ECI_GET_REPLY
or ECI_GET_SPECIFIC_REPLY to receive the actual response.
The following field is a required parameter for notification by semaphore:
v eci_async_notify.sem_handle refers to the semaphore.
Fields to support ECI extensions
Environment-dependent extensions
The following fields in the ECI parameter block are to support
environment-dependent extensions.
eci_async_notify.window_handle
(Windows environment, ECI_ASYNC_NOTIFY_MSG and
ECI_STATE_ASYNC_MSG call types)
The handle of the window to which the reply message will be posted.
The ECI uses this field as input only.
Note: eci_window_handle is a synonym for this parameter.
eci_async_notify.sem_handle
(Windows environment, ECI_ASYNC_NOTIFY_SEM and
ECI_STATE_ASYNC_SEM call types)
Windows applications should pass an event object handle.
The ECI uses this field as input only.
eci_async_notify.win_fields.hwnd
The handle of the Windows window to which the reply message will
be posted.
The ECI uses this field as input only.
eci_async_notify.win_fields.hinstance
The Windows hInstance of the calling program as supplied during
program initialization.
The ECI uses this field as input only.
eci_sync_wait.hwnd
The handle of the window that is to be disabled during the
synchronous call.
The ECI uses this field as input only.
Appendix A. ECI extensions that are environment-dependent 163

Environment-dependent extensions
eci_message_id
(Windows environment, ECI_ASYNC_NOTIFY_MSG and
ECI_STATE_ASYNC_MSG call types)
The message identifier to be used for posting the reply message to the
window specified in the relevant window handle.
The ECI uses this field as input only.
Reply message formats
When an application makes an asynchronous call requesting notification by
message, the ECI returns the result in a message to a window using the
specified window handle and message identifier.
ECI return notification
For Windows, the message is divided into two parameters, as follows:
wParam
High-order 16 bits
Specified message qualifier
Low-order 16 bits
Return code
lParam
4-character abend code, if applicable
Table 9. CICS_ExternalCall return codes — environment-dependent extensions
Return code Meaning
ECI_ERR_NULL_WIN_HANDLE An asynchronous call was specified with
the window handle set to 0.
ECI_ERR_NULL_MESSAGE_ID An asynchronous call was specified with
the message identifier set to 0.
ECI_ERR_NULL_SEM_HANDLE A null semaphore handle was passed
when a valid handle was required.
Summary of input parameter requirements
Table 10 on page 166 shows the input parameters for an ECI call, and, for each
call type, whether the parameters are required (R), optional (O), or not
applicable (-). Where a parameter is shown as optional or not-applicable an
initial field setting of nulls is recommended. An asterisk (*) immediately
following an R means that further details regarding applicability are given
under the description of the parameter.
164 CICS Transaction Gateway: Programming Guide

Environment-dependent extensions
The following abbreviations are used in the Parameter column:
AN async_notify
WF win_fields
SW sync_wait
Also, all named parameters have an eci_ prefix. Thus AN.WF.hwnd represents
the eci_async_notify.win_fields.hwnd parameter.
The following 3-character abbreviations are used for the call types in the
column headings of the table:
ANM ECI_ASYNC_NOTIFY_MSG
ANS ECI_ASYNC_NOTIFY_SEM
SAM ECI_STATE_ASYNC_MSG
SAS ECI_STATE_ASYNC_SEM
SYN ECI_SYNC
SSN ECI_STATE_SYNC
Appendix A. ECI extensions that are environment-dependent 165

Environment-dependent extensions
Table 10. Input parameters for CICS_ExternalCall — environment-dependent
extensions
Parameter, eci_ ANM ANS SAM SAS SYN SSN
call_type R R R R R R
program_name R* R* - - R* -
userid R R - - R -
password R R - - R -
transid O O - - O -
commarea O O R* R* O R*
commarea_length O O R* R* O R*
timeout O O O O O O
extend_mode R R R R R R
AN.window_handle R* - R* - - -
AN.sem_handle - R - R - -
AN.WF.hwnd R* - R* - - -
AN.WF.hinstance R* - R* - - -
SW.hwnd - - - - R* R*
message_id R - R - - -
message_qualifier O O O O O O
luw_token R R R* R* R R*
version O O O O O O
system_name O O O O O O
166 CICS Transaction Gateway: Programming Guide

|
|
|
|
Appendix B. Sample Programs
Samples are supplied in subdirectories of the \samples
directory. See file samples.txt, inthe\samples directory, for
details, including compilation instructions and information on compiler
considerations.
For each language, different levels of sample are provided. These include
v A simple sample to allow you to test that the CICS Transaction Gateway is
functioning and to give you a feel for the basic requirements of a Client
application.
v More complex samples that demonstrate advanced API features, and
provide a more realistic example of a Client application.
As far as possible the sample code adheres to the language standards, for
example, ANSI C. The samples are all driven from the command line to avoid
any dependence on platform-specific GUI code.
For information on the languages and compilers supported on each CICS
Transaction Gateway platform, refer to the CICS Transaction Gateway:
Administration book for your operating system.
© Copyright IBM Corp. 2002 167

168 CICS Transaction Gateway: Programming Guide

|
|
|
|
Appendix C. ECI and EPI exits
This Appendix describes exits you can add to the EPI and ECI when using
Client daemon. The exits allow you to influence the processing of ECI and EPI
calls for certain application requests.
The Appendixt is organized as follows:
“Installing the exits”
“Writing your own user exits” on page 171
“How the exit routines are described in the reference sections” on page 171
“ECI exits reference” on page 171
“Diagnostic information” on page 203
“CICSTERM, CICSPRNT and the EPI exits” on page 203
Installing the exits
During ECI and EPI initialization, CICS Transaction Gateway attempts to load
the objects described in Table 11 from the \bin subdirectory,
and to call the corresponding entry points.
Table 11. ECI and EPI exits
Object name Entry point name
ECI CICSECIX CICS_EciExitInit
EPI CICSEPIX CICS_EpiExitInit
Each entry point is passed a single parameter, a pointer to a structure that
contains a list of addresses. The initialization code of the program puts the
addresses of all the exits into the structure, and then the exits are called at
appropriate points in ECI and EPI processing. Because the exits are entered by
using the addresses supplied, you may give the exits any valid names. In this
book, conventional names are used for the exits.
If the objects are not found, no exit processing occurs.
Four sample user exit files are supplied: ecix1.c, ecix2.c, epix1.c, and
epix2.c in:
v \samples\c\exits on Windows
v /samples/c on UNIX operating systems
© Copyright IBM Corp. 2002 169

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
ECI and EPI exits
These exits allow server aliases to be used. They redirect requests to a server
other than that specified by the Client application. See file
\samples\samples.txt for more details about the samples, and
how to edit them for your system. To install the samples:
1. make any required changes to the details of servers and aliases
2. to make files CICSECIX and CICSEPIX:
v on Windows, run ecix1mak.cmd and epix1mak.cmd
v on UNIX operating systems, run csamp.mak
3. copy CICSECIX and CICSEPIX to the \bin subdirectory
The following files are also supplied with your CICS Transaction Gateway to
help with programming the exits. Unless otherwise specified, the path to the
files is \samples\c\exits on Windows systems,
/samples/c on UNIX systems.
cicsecix.h
A header file in the \include directory that defines:
v inputs and outputs for each ECI exit
v the format of the list of addresses for calling ECI exits
v data structures used by ECI exits
v return code values for ECI exits.
cicsepix.h
A header file in the \include directory that defines:
v inputs and outputs for each EPI exit
v the format of the list of addresses for calling EPI exits
v data structures used by EPI exits
v return code values for EPI exits.
ecix1.c A template that you can use to write your own ECI user exits. It does
not perform any actions if you compile it.
epix1.c
A template that you can use to write your own EPI user exits. It does
not perform any actions if you compile it.
Note: If you write a user-exit DLL, you must include all exits, apart from the
following:
v CICS_EciSetProgramAlias is optional.
v Include either CICS_EpiTermIdExit or CICS_EpiTermIdInfoExit.
New DLLs should use CICS_EpiTermIdInfoExit.
170 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
|
|
|
|
|
Writing your own user exits
Follow these rules:
v Do not make EPI or ECI calls from the exit.
v To minimize the impact on performance, keep executable code to a
minimum.
v Ensure that all your exit code is re-entrant and thread-safe.
v Name the primary entry points as follows:
ECI CICS_ECIEXITINIT
EPI CICS_EPIEXITINIT
You may change the names of the actual exits; do not change the parameter
lists.
v Ensure that your user exit programs contain valid entry points for all of the
user exit functions, with the exception of CICS_EciSetProgramAliasExit,
which is optional.
How the exit routines are described in the reference sections
The exit routines are described under the following headings:
v Purpose—describes the kind of processing that the exit is intended to
perform.
v When called—describes where in ECI or EPI processing the exit is called.
v Parameters—describes the parameters supplied to the exit. Parameters are
classified as follows:
– Input—the exit may look at it, but must not change it.
– Output—the exit must not look at it, but must store a value in it.
– Input-output—the exit may look at it, and may store a value in it.
v Return codes—describes the possible values the exit can return to the ECI
or EPI. In each case the subsequent behavior of the ECI or EPI is described.
ECI exits reference
In this section the following exits are discussed:
v CICS_EciInitializeExit
v CICS_EciTerminateExit
v CICS_EciExternalCallExit1
v CICS_EciExternalCallExit2
v CICS_EciSystemIdExit
v CICS_EciDataSendExit
v CICS_EciDataReturnExit
v CICS_EciSetProgramAliasExit
ECI and EPI exits
Appendix C. ECI and EPI exits 171

ECI exits
Table 12 summarizes the exit names, the parameters passed to each exit, and
the possible return codes.
Table 12. Summary of ECI exits
Function name Parameters Return codes:
CICS_EciInitializeExit Version CICS_EXIT_OK
Anchor CICS_EXIT_NO_EXIT
CICS_EXIT_CANT_INIT_EXITS
user-defined
CICS_EciTerminateExit Anchor CICS_EXIT_OK
CICS_EXIT_BAD_ANCHOR
CICS_EXIT_BAD_STORAGE
user-defined
CICS_EciExternalCallExit1 Anchor CICS_EXIT_OK
Token
CICS_EXIT_BAD_ANCHOR
ParmPtr CICS_EXIT_BAD_PARM
user-defined
CICS_EciExternalCallExit2 Anchor CICS_EXIT_OK
Token
CICS_EXIT_BAD_ANCHOR
ParmPtr CICS_EXIT_BAD_PARM
user-defined
CICS_EciSystemIdExit Anchor CICS_EXIT_OK
Token
CICS_EXIT_BAD_ANCHOR
ParmPtr CICS_EXIT_BAD_PARM
Reason CICS_EXIT_GIVE_UP
user_defined
CICS_EciDataSendExit Anchor CICS_EXIT_OK
Token
CICS_EXIT_BAD_ANCHOR
CICS_EXIT_BAD_PARM
user_defined
CICS_EciDataReturnExit Anchor CICS_EXIT_OK
Token
CICS_EXIT_BAD_ANCHOR
ParmPtr CICS_EXIT_BAD_PARM
user_defined
CICS_EciSetProgramAliasExit Anchor CICS_EXIT_OK
EciParms CICS_EXIT_BAD_ANCHOR
Program CICS_EXIT_BAD_PARM
user_defined
Identification token
In order for the exits to be able to relate calls for the same ECI request, an
identification token is passed in as a parameter to all exits except
CICS_EciInitializeExit and CICS_EciTerminateExit. The token is the same for
CICS_EciExternalCallExit1 and CICS_EciExternalCallExit2 that relate to the
same call, and on intervening CICS_EciDataSendExit,
172 CICS Transaction Gateway: Programming Guide

ECI exits
CICS_EciDataReturnExit, and CICS_EciSystemIdExit exits. (Note that
CICS_EciExternalCallExit1 and CICS_EciExternalCallExit2 are not called for
a reply solicitation request.)
The token is unique within the operating system that initiated the request, for
the duration of the request. It may be reused once the last exit for the request
has been called.
In the case of an extended logical unit of work, the token may be different on
different requests within the logical unit of work. (Since we allow reuse of the
token, and a new program link call may not be made until the
ECI_GET_REPLY request for the previous asynchronous request has
completed, it may also be the same.)
The token is 8 bytes long. 8 null bytes is not a valid value for the token and is
not supplied to the exits.
Process model implementation
All exits that relate to a particular request (i.e. have the same identification
token) are called in the context of the application process.
Appendix C. ECI and EPI exits 173

ECI exits
CICS_EciInitializeExit
Function name:
CICS_EciInitializeExit
Parameters
Version
Anchor
Purpose: To allow the user to set up an exit environment.
When called: On the first invocation of CICS_ExternalCall, for each process,
after parameter validation has occurred.
Parameters:
Version Input parameter. The version of the ECI under which the exit
is running.
Anchor Output parameter. A pointer to a pointer that will be passed
to the ECI exits. The second pointer is not used by the ECI; it
is passed to the exits as supplied. You can acquire storage in
this exit and pass its address to the other exits.
Return codes:
CICS_EXIT_OK
The ECI continues processing this request, calling the exits where
appropriate.
CICS_EXIT_NO_EXIT
The ECI continues processing this request, but does not call any more
exits.
CICS_EXIT_CANT_INIT_EXITS
The ECI writes a CICS Transaction Gateway trace record, and then
continues processing this request, but does not call any more exits.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
trace record, and then continues processing this request, but does not
call any more exits.
174 CICS Transaction Gateway: Programming Guide

CICS_EciTerminateExit
Function name:
CICS_EciTerminateExit
Parameters
Anchor
Purpose: To allow the user to clean up the exit environment. Any storage
acquired by CICS_EciInitializeExit must be released in this exit.
CICS_EciTerminateExit is not called by the Client daemon.
When called: On termination of the process that issued the
CICS_EciInitializeExit.
Parameters:
Anchor
Input parameter. The pointer set up by CICS_EciInitializeExit.
ECI exits
Return codes:
CICS_EXIT_OK
Termination continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The ECI writes a CICS
Transaction Gateway trace record, and then continues with
termination.
CICS_EXIT_BAD_STORAGE
CICS detected a storage error. The ECI writes a CICS Transaction
Gateway trace record, and then continues with termination.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
trace record, and then continues with termination.
Appendix C. ECI and EPI exits 175

ECI exits
CICS_EciExternalCallExit1
Function name:
CICS_EciExternalCallExit1
Parameters:
Anchor
Token
ParmPtr
Purpose: To allow the user to pick the best system to run the program. This
exit is called exactly once on each program link and each status information
call. It is not called on a reply solicitation call. Although the exit is called
when eci_luw_token is not zero, any change it makes to eci_system_name is
ignored, as the server was selected when the logical unit of work was started.
When called: On invocation of CICS_ExternalCall, for each program link
call and each status information call, after the ECI has validated the
parameters.
Parameters:
Anchor Input parameter. The pointer set up by
CICS_EciInitializeExit.
Token Input parameter. The identification token established by the
ECI for this request.
ParmPtr Input parameter. A pointer to the ECI parameter block. The
exit must treat all fields in the ECI parameter block as inputs,
except the eci_system_name field, which it may change.
Return codes:
CICS_EXIT_OK
The ECI continues to process the request with the eci_system_name
now specified in the ECI parameter block.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The ECI writes a CICS
Transaction Gateway trace record, and then continues to process the
request with the eci_system_name now specified in the ECI parameter
block.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The ECI writes a CICS
Transaction Gateway trace record, and then continues to process the
request with the eci_system_name now specified in the ECI parameter
block.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
176 CICS Transaction Gateway: Programming Guide

trace record, and then continues to process the request with the
eci_system_name now specified in the ECI parameter block.
ECI exits
Notes: There is a limited set of conditions under which the exit may select a
new system. The exit may select a system if the call is a program link or
status information call, and if a new logical unit of work is being started. In
other cases, the exit should return CICS_EXIT_OK.
If the calling application has put binary zeros as the system name in the
parameter block, then the application is expecting that the system will be
dynamically selected, and the exit may safely select the system.
If however the calling application has placed a system name in the parameter
block, or if the application is a version 0 application, then it may not be
expecting the target system to change, and application errors could result. In
this case the exit would generally return without specifying a replacement
system, with the result that the specified or default system name is to be used.
If the exit chooses to change the selected system in this situation, then it may
do so, but the following should be borne in mind.
v The exit routine must be sensitive to whether or not the modification of the
target system will cause errors in the ECI application running on the client.
v The exit routine must maintain a knowledge base, keyed on appropriate
data available to it, to enable it to determine whether this modification is
acceptable to the client application.
Appendix C. ECI and EPI exits 177

ECI exits
CICS_EciExternalCallExit2
Function name:
CICS_EciExternalCallExit2
Parameters:
Anchor
Token
ParmPtr
Purpose: To allow the user to see the results of synchronous ECI calls for
information gathering purposes only. This exit is called exactly once on every
application program link or status information call. It is not called on reply
solicitation calls.
When called: Before the ECI call returns to the application, and after the
return data is filled into the ECI parameter block.
Parameters:
Anchor Input parameter. The pointer set up by
CICS_EciInitializeExit.
Token Input parameter. The identification token established by the
ECI for this request.
ParmPtr Input parameter. A pointer to the ECI parameter block. The
exit must treat all fields in the ECI parameter block as inputs.
Return codes:
CICS_EXIT_OK
The ECI returns control to the application that issued the
CICS_ExternalCall request.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The ECI writes a CICS
Transaction Gateway trace record, and then returns control to the
application that issued the CICS_ExternalCall request.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The ECI writes a CICS
Transaction Gateway trace record, and then returns control to the
application that issued the CICS_ExternalCall request.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
trace record, and then returns control to the application that issued
the CICS_ExternalCall request.
178 CICS Transaction Gateway: Programming Guide

CICS_EciSystemIdExit
Function name:
CICS_EciSystemIdExit
Parameters:
Anchor
Token
ParmPtr
Reason
ECI exits
Purpose: To allow the user to supply a new system name when the name
supplied in the ECI parameter block is not valid.
When called: This exit is called when an error occurs that may be corrected
by selection of a new system, userid, or password. This would be when the
ECI has returned one of the following codes:
v ECI_ERR_NO_CICS
v ECI_ERR_UNKNOWN_SERVER
v ECI_ERR_SECURITY_ERROR
v ECI_ERR_SYSTEM_ERROR
v ECI_ERR_RESOURCE_SHORTAGE
v ECI_ERR_MAX_SYSTEMS.
It may be called when either when the Client daemon detects an error before
data is sent to the server, or after data returns from the server.
Parameters:
Anchor Input parameter. The pointer set up by
CICS_EciInitializeExit.
Token Input parameter. The identification token established by the
ECI for this request.
ParmPtr Input parameter. A pointer to the ECI parameter block. The
exit must treat all fields in the ECI parameter block as inputs,
except the following, which it may set:
v eci_system_name
v eci_userid
v eci_password.
Reason Input parameter. The reason code that explains why the
application request has not so far succeeded.
Return codes:
CICS_EXIT_OK
The ECI retries the application call using the new parameters in the
ECI parameter block. (The CICS program communication area
Appendix C. ECI and EPI exits 179

ECI exits
supplied by the application to the CICS_ExternalCall is preserved.)
The application callback routine will not be called, nor will
CICS_EciExternalCallExit2.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The ECI writes a CICS
Transaction Gateway trace record, and then returns to the application
that issued the CICS_ExternalCall request.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The ECI writes a CICS
Transaction Gateway trace record, and then returns to the application
that issued the CICS_ExternalCall request.
CICS_EXIT_GIVE_UP
The ECI returns to the application that issued the CICS_ExternalCall
request.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
trace record, and then retries the application call as described for
CICS_EXIT_OK.
180 CICS Transaction Gateway: Programming Guide

CICS_EciDataSendExit
Function name:
CICS_EciDataSendExit
Parameters:
Anchor
Token
Purpose: To allow the user to time calls for performance analysis.
ECI exits
When called: As close as possible to the time that the request will be sent to
the server.
Parameters:
Anchor Input parameter. The pointer set up by
CICS_EciInitializeExit.
Token Input parameter. The identification token established by the
ECI for this request.
Return codes:
CICS_EXIT_OK
The ECI continues processing the request.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The ECI writes a CICS
Transaction Gateway trace record, and then continues processing the
request.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The ECI writes a CICS
Transaction Gateway trace record, and then continues processing the
request.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
trace record, and then continues processing the request.
Appendix C. ECI and EPI exits 181

ECI exits
CICS_EciDataReturnExit
Function name:
CICS_EciDataReturnExit
Parameters:
Anchor
Token
ParmPtr
Purpose: To allow the user to time calls for performance analysis.
When called: As close as possible to the time that the response from the
server has been received, and the ECI block and commarea data for eventual
return to the application has been built. It is also called if there is a timeout
because of a lack of response from the server.
Parameters:
Anchor Input parameter. The pointer set up by
CICS_EciInitializeExit.
Token Input parameter. The identification token established by the
ECI for this request.
ParmPtr Input parameter. A pointer to the ECI parameter block. The
exit must treat all fields in the ECI parameter block as inputs.
Return codes:
CICS_EXIT_OK
The ECI continues processing the request.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The ECI writes a CICS
Transaction Gateway trace record, and then continues processing the
request.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The ECI writes a CICS
Transaction Gateway trace record, and then continues processing the
request.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
trace record, and then continues processing the request.
182 CICS Transaction Gateway: Programming Guide

CICS_EciSetProgramAliasExit
Function name:
CICS_EciSetProgramAliasExit
Parameters:
Anchor
EciParms
Program
Purpose: To allow the user to change the program name that the WorkLoad
Manager of CICS Transaction Gateway for Windows uses for load balancing
This exit is only available when the WorkLoad Manager is enabled.
When called: Immediately before the WorkLoad Manager tries to select a
server for an ECI program to connect to.
Parameters:
Anchor Input parameter. The pointer set up by
CICS_EciInitializeExit.
ECIParms ECI parameter block.
Program The alias name of the ECI program that the WorkLoad
Manager will use for load balancing.
ECI exits
Return codes:
CICS_EXIT_OK
The ECI continues processing the request.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The ECI writes a CICS
Transaction Gateway trace record, and then continues processing the
request.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The ECI writes a CICS
Transaction Gateway trace record, and then continues processing the
request.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The ECI writes a CICS Transaction Gateway
trace record, and then continues processing the request.
Appendix C. ECI and EPI exits 183

EPI exits
EPI exits reference
In this section the following exits are discussed:
v CICS_EpiInitializeExit
v CICS_EpiTerminateExit
v CICS_EpiAddTerminalExit
v CICS_EpiTermIdExit
v CICS_EpiTermIdInfoExit
v CICS_EpiStartTranExit
v CICS_EpiReplyExit
v CICS_EpiDelTerminalExit
v CICS_EpiGetEventExit
v CICS_EpiSystemIdExit
v CICS_EpiTranFailedExit
Table 13 summarizes the exit names, the parameters passed to each exit, and
the possible return codes.
Table 13. Summary of EPI exits
Function name Parameters Return codes:
CICS_EpiInitializeExit Version
CICS_EXIT_OK
Anchor
CICS_EXIT_NO_EXIT
CICS_EXIT_CANT_INIT_EXITS
user-defined
CICS_EpiTerminateExit Anchor CICS_EXIT_OK
CICS_EXIT_BAD_ANCHOR
CICS_EXIT_BAD_STORAGE
user-defined
CICS_EpiAddTerminalExit Anchor
CICS_EXIT_OK
NameSpace CICS_EXIT_DONT_ADD_TERMINAL
System
CICS_EXIT_BAD_ANCHOR
NetName
CICS_EXIT_BAD_PARM
DevType
user-defined
CICS_EpiTermIdExit Anchor
CICS_EXIT_OK
TermIndex
CICS_EXIT_BAD_ANCHOR
System
CICS_EXIT_BAD_PARM
user-defined
CICS_EpiTermIdInfoExit Anchor
CICS_EXIT_OK
Version
CICS_EXIT_BAD_ANCHOR
TermIndex
CICS_EXIT_BAD_PARM
EpiDetails
user-defined
CICS_EpiStartTranExit Anchor
CICS_EXIT_OK
TransId
CICS_EXIT_BAD_ANCHOR
Data
CICS_EXIT_BAD_PARM
Size
user-defined
184 CICS Transaction Gateway: Programming Guide

Table 13. Summary of EPI exits (continued)
Function name Parameters Return codes:
CICS_EpiReplyExit Anchor
CICS_EXIT_OK
TermIndex
CICS_EXIT_BAD_ANCHOR
Data
CICS_EXIT_BAD_PARM
Size
user_defined
CICS_EpiDelTerminalExit Anchor
CICS_EXIT_OK
TermIndex
CICS_EXIT_BAD_ANCHOR
CICS_EXIT_BAD_PARM
user_defined
CICS_EpiGetEventExit Anchor
CICS_EXIT_OK
TermIndex
CICS_EXIT_BAD_ANCHOR
Wait
CICS_EXIT_BAD_PARM
Event
user_defined
CICS_EpiSystemIdExit Anchor
CICS_EXIT_OK
NameSpace CICS_EXIT_DONT_ADD_TERMINAL
System
CICS_EXIT_BAD_ANCHOR
NetName
CICS_EXIT_BAD_PARM
DevType
FailedSystem
Reason
SubReason
UserId
PassWord
user_defined
CICS_EpiTranFailedExit Anchor
TermIndex
Wait
Event
CICS_EXIT_OK
CICS_EXIT_BAD_ANCHOR
CICS_EXIT_BAD_PARM
user_defined
EPI exits
Appendix C. ECI and EPI exits 185

EPI exits
CICS_EpiInitializeExit
Function name:
CICS_EpiInitializeExit
Parameters:
Version
Anchor
Purpose
To allow the user to set up an exit environment.
When called
On each invocation of CICS_EpiInitialize, after the EPI has validated the
parameters.
Parameters
Version Input parameter. The version of the EPI under which the exit
is running.
Anchor Output parameter. A pointer to a pointer that will be passed
to the EPI exits. The second pointer is not used by the EPI; it
is passed to the exits as supplied. You can acquire storage in
this exit and pass its address to the other exits.
Return codes
CICS_EXIT_OK
The EPI continues processing this request, calling the exits where
appropriate.
CICS_EXIT_NO_EXIT
The EPI continues processing this request, but does not call any more
exits.
CICS_EXIT_CANT_INIT_EXITS
The EPI writes a CICS Transaction Gateway trace record, and then
continues processing this request, but does not call any more exits.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then continues processing this request, but does not
call any more exits.
186 CICS Transaction Gateway: Programming Guide

CICS_EpiTerminateExit
Function name:
CICS_EpiTerminateExit
Parameters:
Anchor
Purpose
To allow the user to clean up the exit environment. Any storage acquired by
CICS_EpiInitializeExit must be released in this exit.
When called
On each invocation of CICS_EpiTerminate, after the EPI has validated the
parameters.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
EPI exits
Return codes
CICS_EXIT_OK
Termination continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then continues with
termination.
CICS_EXIT_BAD_STORAGE
CICS detected a storage error. The EPI writes a CICS Transaction
Gateway trace record, and then continues with termination.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then continues with termination.
Appendix C. ECI and EPI exits 187

EPI exits
CICS_EpiAddTerminalExit
Function name:
CICS_EpiAddTerminalExit
Parameters:
Anchor
NameSpace
System
NetName
DevType
Purpose
To allow the user to select a server, or override the one passed to
CICS_EpiAddTerminal or CICS_EpiAddExTerminal in the System parameter.
When called
On each invocation of CICS_EpiAddTerminal or CICS_EpiAddExTerminal,
after the EPI has validated the parameters.
Parameters
Anchor Input parameter. The pointer storage set up by
CICS_EpiInitializeExit.
NameSpace Input-output parameter. On input, its value depends on the
value supplied for the NameSpace parameter of the
CICS_EpiAddTerminal or CICS_EpiAddExTerminal call to
which this exit relates:
v If a null pointer was supplied, this input is a pointer to a
null string.
v If a non-null pointer was supplied, the Namespace input
parameter points to a copy of this data.
On output, it will be used by the EPI in the same way as the
value specified on the call would have been used.
System Input-output parameter. On input, it is the value supplied for
the System parameter of the CICS_EpiAddTerminal or
CICS_EpiAddExTerminal call to which this exit relates. On
output, it will be used by the EPI in the same way as the
value specified on the call would have been used.
NetName Input-output parameter. On input, it is the value supplied for
the NetName parameter of the CICS_EpiAddTerminal or
CICS_EpiAddExTerminal call to which this exit relates. On
output, it will be used by the EPI in the same way as the
value specified on the call would have been used.
DevType Input-output parameter. On input, it is the value supplied for
the DevType parameter of the CICS_EpiAddTerminal or
CICS_EpiAddExTerminal call to which this exit relates. On
188 CICS Transaction Gateway: Programming Guide

output, it will be used by the EPI in the same way as the
value specified on the call would have been used.
Return codes
CICS_EXIT_OK
Processing continues with the output values of NameSpace, System,
NetName, and DevType.
CICS_EXIT_DONT_ADD_TERMINAL
The CICS_EpiAddTerminal or CICS_EpiAddExTerminal is ended
with a return code of CICS_EPI_ERR_FAILED. If the application uses
CICS_EpiGetSysError, the value 109 is returned in the Cause field of
the CICS_EpiSysError_t structure.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then continues as for
CICS_EXIT_OK.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then continues as for
CICS_EXIT_OK.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then continues as for CICS_EXIT_OK.
Notes
Note on selection of systems:
EPI exits
If the calling application does not specify system name in its parameter list,
then it is expecting that the system will be dynamically selected, and the exit
may safely select the system.
If however the calling application specifies a system name, then it may not be
expecting the target system to change and application errors could result. In
this case the exit would generally not specify a replacement system, with the
result that the specified or default system name, device type, etc. is to be
used. If the exit chooses to change the selected system in this situation, then it
may do so, but the following should be borne in mind.
v The exit routine must be sensitive to whether or not the modification of the
target system will cause errors in the EPI application running on the client.
v The exit routine must maintain a knowledge base, keyed on appropriate
data available to it, to enable it to determine whether this modification is
acceptable to the client application.
Appendix C. ECI and EPI exits 189

EPI exits
CICS_EpiAddTerminalExit and CICS_EpiSystemIdExit:
The relationship between these exits is as follows. The exits will get multiple
chances to make a selection of the system. The first chance will always occur
on the CICS_EpiAddTerminalExit. This exit will only receive the parameters
passed by the application to CICS_EpiAddTerminal or
CICS_EpiAddExTerminal. If an error occurs when CICS tries to add the
terminal (whether or not the exit has made a selection) then
CICS_EpiSystemIdExit will be called. CICS_EpiSystemIdExit will
additionally be passed the error that occurred on the attempt to add the
terminal, and will get a chance to correct the error. This continues to occur
until either a terminal is successfully added, or until CICS_EpiSystemIdExit
signals to give up.
If no error occurs on the attempt to add the terminal, then
CICS_EpiSystemIdExit will not be called.
190 CICS Transaction Gateway: Programming Guide

CICS_EpiTermIdExit
Function name:
CICS_EpiTermIdExit
Parameters:
Anchor
TermIndex
System
EPI exits
Purpose
To allow the user to know the terminal index allocated after a successfull call
to CICS_EpiAddTerminal.
CICS_EpiTermIdExit is provided for compatibility with older applications
only. All new applications that use the EPI exits should use
CICS_EpiTermIdInfoExit instead.
When called
On each invocation of CICS_EpiAddTerminal, after the server has allocated
the terminal.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
TermIndex Input parameter. This is the terminal index for the terminal
resource just reserved or installed.
System Input parameter. A pointer to a null-terminated string that
specifies the name of the server in which the terminal resource
has been reserved or installed.
Return codes
CICS_EXIT_OK
Processing continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then continues as for
CICS_EXIT_OK.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then continues as for
CICS_EXIT_OK.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then continues as for CICS_EXIT_OK.
Appendix C. ECI and EPI exits 191

EPI exits
CICS_EpiTermIdInfoExit
Function name:
CICS_EpiTermIdInfoExit
Parameters:
Anchor
Version
TermIndex
EpiDetails
Purpose
To allow the user to retrieve information about the current terminal.
When called
Immediately after a CICS terminal has been installed
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
Version Input parameter. The EPI version.
TermIndex Input parameter. The index of the terminal being installed.
EpiDetails Input parameter. A pointer to the CICS_EpiDetails_t
structure, containing details about the terminal being installed.
Return codes
CICS_EXIT_OK
Processing continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then continues as for
CICS_EXIT_OK.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then continues as for
CICS_EXIT_OK.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then continues as for CICS_EXIT_OK.
192 CICS Transaction Gateway: Programming Guide

CICS_EpiStartTranExit
Function name:
CICS_EpiStartTranExit
Parameters:
Anchor
TransId
Data
Size
Purpose
To allow the user to see when a transaction is started, for information
gathering purposes. This exit will not select a system, and has no return data.
When called
On invocation of CICS_EpiStartTran, after the EPI has validated the
parameters.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
TransId Input parameter. The value supplied for the TransId
parameter of the CICS_EpiStartTran call to which this exit
relates.
Data Input parameter. The value supplied for the Data parameter
of the CICS_EpiStartTran call to which this exit relates.
Size Input parameter. The value supplied for the Size parameter of
the CICS_EpiStartTran call to which this exit relates.
Return codes
CICS_EXIT_OK
Processing of the CICS_EpiStartTran call continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiStartTran call continues.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiStartTran call continues.
user-defined
User-defined return codes must have a value not less than
EPI exits
Appendix C. ECI and EPI exits 193

EPI exits
194 CICS Transaction Gateway: Programming Guide
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then processing of the CICS_EpiStartTran call
continues.

CICS_EpiReplyExit
Function name:
CICS_EpiReplyExit
Parameters:
Anchor
TermIndex
Data
Size
Purpose
To allow the user to see when a transaction is replied to, for information
gathering purposes.
EPI exits
When called
On invocation of CICS_EpiReply, after the EPI has validated the parameters.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
TermIndex Input parameter. The value supplied for the TermIndex
parameter of the CICS_EpiReply call to which this exit
relates.
Data Input parameter. The value supplied for the Data parameter
of the CICS_EpiReply call to which this exit relates.
Size Input parameter. The value supplied for the Size parameter of
the CICS_EpiReply call to which this exit relates.
Return codes
CICS_EXIT_OK
Processing of the CICS_EpiReply call continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiReply call continues.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiReply call continues.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then processing of the CICS_EpiReply call
continues.
Appendix C. ECI and EPI exits 195

EPI exits
CICS_EpiDelTerminalExit
Function Name:
CICS_EpiDelTerminalExit
Parameters:
Anchor
TermIndex
Purpose
To allow the user to clean up any terminal-related data structures.
When called
On invocation of CICS_EpiDelTerminal or CICS_EpiPurgeTerminal, after the
EPI has validated the parameters. To allow the user to clean up any
terminal-related data structures.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
TermIndex Input parameter. The value supplied for the TermIndex
parameter of the CICS_EpiDelTerminal or
CICS_EpiPurgeTerminal call to which this exit relates.
Return codes
CICS_EXIT_OK
Processing of the CICS_EpiDelTerminalor CICS_EpiPurgeTerminal
call continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiDelTerminal or CICS_EpiPurgeTerminal call continues.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiDelTerminal or CICS_EpiPurgeTerminal call continues.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then processing of the CICS_EpiDelTerminal or
CICS_EpiPurgeTerminal call continues.
196 CICS Transaction Gateway: Programming Guide

CICS_EpiGetEventExit
Function name:
CICS_EpiGetEventExit
Parameters:
Anchor
TermIndex
Wait
Event
Purpose
To allow the user to collect data relating to the event that has arrived.
When called
Immediately before CICS_EpiGetEvent returns to the caller. The exit can then
examine the data returned, time the response from the system, etc.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
TermIndex Input parameter. The value to be returned to the application
in the TermIndex parameter of the CICS_EpiGetEvent call to
which this exit relates.
Wait Input parameter. The value supplied for the Wait parameter of
the CICS_EpiGetEvent call to which this exit relates.
Event Input parameter. The value to be returned to the application
in the Event parameter of the CICS_EpiGetEvent call to
which this exit relates.
Return codes
CICS_EXIT_OK
Processing of the CICS_EpiGetEvent call continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiGetEvent call continues.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiGetEvent call continues.
user-defined
User-defined return codes must have a value not less than
EPI exits
Appendix C. ECI and EPI exits 197

EPI exits
198 CICS Transaction Gateway: Programming Guide
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then processing of the CICS_EpiGetEvent call
continues.

CICS_EpiSystemIdExit
Function name:
CICS_EpiSystemIdExit
Parameters:
Anchor
NameSpace
System
NetName
DevType
FailedSystem
Reason
SubReason
UserId
PassWord
EPI exits
Purpose
To allow the user to supply a new system name when the value supplied for
CICS_Epi_AddTerminal or CICS_EpiAddExTerminal was invalid.
When called
Immediately before CICS_EpiAddTerminal or CICS_EpiAddExTerminal
returns to the application when an error occurred while trying to add the
terminal. The error can be CICS_EPI_ERR_SYSTEM, CICS_EPI_ERR_FAILED,
or CICS_EPI_ERR_SERVER_DOWN. It occurs whether or not
CICS_EpiAddTerminalExit or CICS_EpiAddExTerminal has been called
previously.
Note: On some systems the completion of CICS_EpiAddTerminal or
CICS_EpiAddExTerminal is returned to the application
asynchronously, and in this case this exit will be called asynchronously.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
NameSpace Input-output parameter. The NameSpace parameter used in
the failed CICS_EpiAddTerminal or
CICS_EpiAddExTerminal.
System Input-output parameter. The System parameter used in the
failed CICS_EpiAddTerminal or CICS_EpiAddExTerminal.
NetName Input-output parameter. The NetName parameter used in the
failed CICS_EpiAddTerminal or CICS_EpiAddExTerminal.
DevType Input-output parameter. The DevType parameter used in the
failed CICS_EpiAddTerminal or CICS_EpiAddExTerminal.
FailedSystem Input parameter. The identifier of the system on which the
failure occurred.
Appendix C. ECI and EPI exits 199

EPI exits
Reason Input parameter. The reason for the failure:.
CICS_EPI_ERR_SYSTEM or CICS_EPI_ERR_FAILED.
SubReason Input parameter. More about the failure. If the reason is
CICS_EPI_ERR_FAILED, this is the value that appears in the
Cause field of the CICS_EpiSysError_t structure.
UserId Output parameter. Not used.
PassWord Output parameter. Not used.
Return codes
CICS_EXIT_OK
The EPI will retry the CICS_EpiAddTerminal or
CICS_EpiAddExTerminal call using the values specified as output of
this exit. Note that in this case the considerations described in
“CICS_EpiAddTerminalExit” on page 188 apply.
CICS_EXIT_DONT_ADD_TERMINAL
The CICS_EpiAddTerminal or CICS_EpiAddExTerminal is ended
with a return code of CICS_EPI_ERR_FAILED. If the application uses
CICS_EpiGetSysError, the value 109 is returned in the Cause field of
the CICS_EpiSysError_t structure.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then the error that caused the
exit to be called is returned to the application.
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then the error that caused the
exit to be called is returned to the application.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then the error that caused the exit to be called is
returned to the application.
200 CICS Transaction Gateway: Programming Guide

CICS_EpiTranFailedExit
Function Name:
CICS_EpiTranFailedExit
Parameters:Anchor
TermIndex
Wait
Event
Purpose
To allow the user to collect data when a transaction abends or a terminal fails.
When called
Immediately before CICS_EpiGetEvent returns to the caller, with or without
GetEventExit, when the event is CICS_EPI_EVENT_END_TRAN, and the
AbendCode field is not blank.
Note that there are some failures on remote systems that can occur and will
simply cause the presentation of a 3270 data stream with an error message
and no abend code in the CICS_EPI_EVENT_END_TRAN. This error message
may not even occur on the same event as the CICS_EPI_EVENT_END_TRAN.
If the exit requires to handle this situation, it may monitor it through
CICS_EpiGetEventExit and scan the appropriate 3270 data streams.
Parameters
Anchor Input parameter. The pointer set up by
CICS_EpiInitializeExit.
TermIndex Input parameter. The value to be returned to the application
in the TermIndex parameter of the CICS_EpiGetEvent call to
which this exit relates.
Wait Input parameter. The value supplied for the Wait parameter of
the CICS_EpiGetEvent call to which this exit relates.
Event Input parameter. The value to be returned to the application
in the Event parameter of the CICS_EpiGetEvent call to
which this exit relates.
Return codes
CICS_EXIT_OK
Processing of the CICS_EpiGetEvent call continues.
CICS_EXIT_BAD_ANCHOR
CICS detected an invalid anchor field. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiGetEvent call continues.
EPI exits
Appendix C. ECI and EPI exits 201

EPI exits
CICS_EXIT_BAD_PARM
CICS detected an invalid parameter. The EPI writes a CICS
Transaction Gateway trace record, and then processing of the
CICS_EpiGetEvent call continues.
user-defined
User-defined return codes must have a value not less than
CICS_EXIT_USER_BASE. The EPI writes a CICS Transaction Gateway
trace record, and then processing of the CICS_EpiGetEvent call
continues.
202 CICS Transaction Gateway: Programming Guide

Diagnostic information
The CICS Transaction Gateway traces the input parameters to the exits
immediately before they are called, and the output of the exit when the exit
returns. CICS tracing is not available for use within the exit.
CICSTERM, CICSPRNT and the EPI exits
You can use the CICSTERM and CICSPRNT commands to drive the EPI user
exits. This gives similar load balancing functionality to the Workload Manager
supplied with CICS Transaction Gateway for Windows. See CICS Transaction
Gateway: Windows Administration for more information.
To use the EPI exits, you supply a CICS_EPIEXITINIT function in a DLL
called cicsepix.dll (cicsepix.a on UNIX operating systems). When a
CICSTERM or CICSPRNT session is started, CICS Transaction Gateway looks
for a cicsepix.dll (cicsepix.a) inthe\bin subdirectory. If no
DLL is found, no exit processing occurs.
The CICS_EPIEXITINIT function sets an ExitList structure to point to the
addresses of all the exit functions, which are also contained in cicsepix.dll.
The sample CICS_EPIEXITINIT is as follows:
void CICSEXIT CICS_EPIEXITINIT(CICS_EpiExitList_t *ExitList)
{
}
ExitList->InitializeExit = &CICS_EpiInitializeExit;
ExitList->TerminateExit = &CICS_EpiTerminateExit;
ExitList->AddTerminalExit = &CICS_EpiAddTerminalExit;
ExitList->StartTranExit = &CICS_EpiStartTranExit;
ExitList->ReplyExit = &CICS_EpiReplyExit;
ExitList->DelTerminalExit = &CICS_EpiDelTerminalExit;
ExitList->GetEventExit = &CICS_EpiGetEventExit;
ExitList->TranFailedExit = &CICS_EpiTranFailedExit;
ExitList->SystemIdExit = &CICS_EpiSystemIdExit;
ExitList->TermIdExit = &CICS_EpiTermIdExit;
ExitList->TermIdInfoExit = &CICS_EpiTermIdInfoExit;
EPI exits
As the exits are entered by using the addresses supplied, you can give them
any name you want, as long as their function signature is exactly the same as
the CICS_Epi* functions. Therefore, the ExitList-> exits could be considered as
generic terminal control exits.
InitializeExit is passed a version number of X'FF000000' when driven by
CICSTERM or CICSPRNT. This enables user programs to be able to
differentiate between CICSTERM and CICSPRNT user exits, and EPI user
exits if they wish to do so.
Appendix C. ECI and EPI exits 203

EPI exits
CICSTERM and CICSPRNT also drive the EPI tracepoints.
The following describes the subset of the EPI exits that are available for
CICSTERM and CICSPRNT and how they are implemented. How they affect
the CICS Transaction Gateway terminal emulator behavior is described.
EPI: CICS_EpiInitializeExit
This EPI exit does not affect the running of the calling EPI program,
but it does allow the user to switch the user exits on or off for the
process that calls it. It is called once per process that uses the EPI. It is
called before any other EPI calls take place, and is called at the end of
a successful CICS_EpiInitialize.
CICSTERM: InitializeExit
It is important that this exit is called once only for each CICSTERM
session that is created, because each CICSTERM runs in a separate
process. The version number passed is X'FF000000'.
EPI: CICS_EpiTerminateExit
Called by CICS_EpiTerminate, this is always the last EPI call in a
particular process. It does not affect the running of the calling EPI
program. It is called after checking that the EPI was initialized, and
that there is not an active notify thread, but just before EPI is actually
terminated. The EPI exit DLL is unloaded immediately following the
user exit call.
CICSTERM: TerminateExit
Only called once during CICSTERM termination.
EPI: CICS_EpiAddTerminalExit
Allows the user to select a server, change the server parameters
passed to the EPI call, and refuse to add a terminal to a server. This
all happens from within the EPI call. The EPI program subsequently
refers to the server by an index number, therefore the program does
not need to know what server it is actually connected to. If the user
exit refuses to connect a server, then CICS_EpiSystemIDExit is not
called (see below for further details). CICS_EpiAddTerminalExit is
called after CICS_EpiAddTerminal or CICS_EpiAddExTerminal has
verified that the EPI has been successfully initialized, and that there is
a free session. It is called before the CICS_EpiAddTerminal or
CICS_EpiAddExTerminal call actually sends the terminal definition to
the server.
CICSTERM: AddTerminalExit
The /s or /r parameters of CICSTERM allow the user to specify that
the CICS Transaction Gateway can connect to:
v The first server defined in the CICS Transaction Gateway
configuration file.
v A server chosen by the user from a list of available servers
204 CICS Transaction Gateway: Programming Guide

v A server specified by the /s or /r parameter.
EPI exits
AddTerminalExit receives the system name as a parameter, and can
specify a different server if required, or reject the server and cause the
terminal emulator to terminate. If AddTerminalExit rejects the install,
CICSTERM displays an error to the effect that the server is
unavailable.
EPI: CICS_EpiSystemIdExit
Allows the user to re-select a server if a CICS_EpiAddTerminal or
CICS_EpiAddExTerminal fails. This user exit is called if a
CICS_EpiAddTerminal fails (but not if the
CICS_EpiAddTerminalExit causes the failure). If it returns
CICS_EXIT_OK, CICS_EpiAddTerminal or CICS_EpiAddExTerminal
tries to add the terminal again. The server parameters can be changed
by this exit between retries.
CICS_EpiSystemIdExit can be called asynchronously or
synchronously by EPI programs. CICS_EpiSystemIdExit can be
presented with:
v A CICS_EPI_ERR_SYSTEM error, meaning the server is unknown,
or,
v A CICS_EPI_ERR_SERVER_DOWN error, meaning the server has
failed, or,
v A CICS_EPI_ERR_SECURITY error, for a security failure, or,
v A CICS_EPI_ERR_FAILED error for any other type of failure.
It is also passed a parameter that is the same as the cics_syserr_t data
structure cause field. This value further specifies the error and is a
value specific to the operating environment
CICSTERM: SystemIdExit
If a CICSTERM CICS_EpiAddTerminal or CICS_EpiAddExTerminal
call fails due to the client requester not having enough sessions free
(governed by the Maximum Requsts parameter in the CICS
Transaction Gateway configuration file ) then SystemIdExit is called
with CICS_EPI_ERR_FAILED as the primary reason code and 7046 as
the secondary reason code. The secondary reason code number is the
same as the client trace number for a resource shortage (CCL7046E).
In all other cases of CICS_EPI_ERR_FAILED, CICSTERM passes a
secondary reason code of 0.
If no user exits are active, then CICSTERM retries a terminal install if
it fails due to there not being enough available sessions. (This allows
terminals to wait for free sessions before being installed.) If there are
user exits available, then any retry behavior is controlled completely
by the exit.
Appendix C. ECI and EPI exits 205

EPI exits
CICS_EpiSystemId is always called synchronously from the terminal
thread, that is, the terminal install response is sent, it waits for a reply,
and then drives SystemIdExit if the response is bad.
EPI: CICS_EpiTermIdExit
Allows the user to know what EPI Termid an added terminal is given.
This is only called after a terminal has been successfully installed on a
server. It does not affect the running of the EPI program. EPI Termid
numbers are local to each process the EPI program runs under.
CICSTERM: TermIdExit
As only one CICSTERM runs per process, the Termid number is
hardcoded to 1.
EPI: CICS_EpiTermIdInfoExit
Allows the user to know details about a terminal. This is called after a
terminal has been successfully installed on a server.
CICSTERM: TermIdInfoExit
As only one CICSTERM runs per process, the Termid number is
hardcoded to 1.
EPI: CICS_EpiDelTerminalExit
Allows the user to clean up terminal code. It is called when
CICS_EpiDelTerminal is issued. It does not affect the running of the
EPI program.
CICSTERM: DelTerminalExit
As only one CICSTERM runs per process, the Termid number is
hardcoded to 1. It is called just before TerminateExit when the
terminal is ended. When the server fails the AddTerminalExit is
called again when it is restarted. However the DelTerminalExit is not
called when the server fails.
EPI: CICS_EpiStartTranExit
Allows a user to see that a transaction has been started, and to see the
Transid & 3270 data sent to it. It does not affect the running of the EPI
program. CICS_EpiStartTranExit is called after the EPI state has been
verified, and just before the CICS_EpiStartTran is called.
Note that a pseudo-conversational transaction causes the
CICS_EpiStartTranExit to be called because in this case an EPI
program would have to start a transaction again.
CICSTERM: StartTranExit:
If a a non-ATI transaction is being started, then StartTranExit is called,
sending a blank in the Transid field and the TIOA (terminal input
output area) for the Data field. The Transid is either the first four
characters of the TIOA data, or it will follow a 3270 Set Buffer
206 CICS Transaction Gateway: Programming Guide

Address (SBA) command (which begins X'11'). In the latter case, it will
start on the 4th byte of the TIOA (as a SBA command takes up a total
of three bytes).
StartTranExit is not driven for ATI transactions. This is because the
exit is normally driven by the CICS_EpiStartTran API call, and this
call is not made to start ATI transactions. However
pseudo-conversational transactions will drive StartTranExit. This is
because in an EPI program, the user would have to call
CICS_EpiStartTran to start the pseudo-conversational transaction. In
the case of pseudo-conversational transactions, the transaction id is
put in the transid parameter block and the TIOA passed in the data
block does not contain the transaction id.
StartTranExit is not called as a result of an EXEC CICS RETURN
TRANSIDname IMMEDIATE command issued by an application from
a CICSTERM session.
EPI: CICS_EpiReplyExit
Allows the user to see when an application is replied to. It does not
affect the running of the EPI program.
CICSTERM ReplyExit
Activated when the CICS Transaction Gateway is sending data and a
transaction is currently active. The Termid number is hard coded to 1.
The terminal TIOA is passed to ReplyExit
ReplyExit is not called as a result of an EXEC CICS RETURN
TRANSIDname IMMEDIATE command issued by an application from
a CICSTERM session.
The GetEventExit and TranFailedExit exits are not implemented for
CICSTERM and CICSPRNT
EPI exits
Appendix C. ECI and EPI exits 207

208 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The product library and related literature
This chapter lists books on the CICS Transaction Gateway, and related topics.
It also discusses how you can view the online library supplied with the
product.
It consists of the following topics:
“CICS Transaction Gateway books” Read this for a list of all books provided
with the CICS Transaction Gateway.
“Sample configuration documents” on
page 210
Read this for information about a series of
PDF documents that provide step-by-step
guidance on configuring the CICS
Transaction Gateway.
“Redbooks ” on page 211 Read this for details of other publications
that contain examples of client/server
configurations.
“Other Useful Books” on page 211 Read this for details of other relevant
publications.
“Obtaining books from IBM” on page 213 Read this for information on downloading
books and ordering hardcopy versions.
CICS Transaction Gateway books
v CICS Transaction Gateway: Windows Administration, SC34-6190
This book describes the administration of the CICS Transaction Gateway for
Windows.
v CICS Transaction Gateway: UNIX Administration, SC34-6139
This book describes the administration of the CICS Transaction Gateway for
UNIX operating systems.
v CICS Transaction Gateway: z/OS Administration, SC34-6191
This book describes the administration of the CICS Transaction Gateway for
z/OS.
v CICS Transaction Gateway: Gateway Messages
This online book lists and explains the error messages that can be generated
by CICS Transaction Gateway.
You cannot order this book.
v CICS Transaction Gateway: Programming Reference, SC34-6140
© Copyright IBM Corp. 2002 209

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The CICS Transaction Gateway
This book provides information on the APIs of the programming languages
supported by the CICS Transaction Gateway.
There are also additional HTML pages that contain JAVA programming
reference information.
v CICS Transaction Gateway: Programming Guide, SC34-6141
This introduction to programming for the CICS Transaction Gateway
provides the information that you need to allow non-CICS applications to
use CICS facilities in a client/server environment.
Sample configuration documents
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. .
The following scenarios are currently covered:
v Configuring CICS Transaction Gateway for Windows for Microsoft SNA
Server
v Configuring CICS Transaction Gateway for Windows for eNetwork Personal
Communications
v Configuring CICS Transaction Gateway for Windows for TCP62
v Configuring CICS Transaction Gateway for AIX for IBM eNetwork
Communications Server
v Configuring CICS Transaction Gateway for Windows for Communications
Server
v Configuring CICS Transaction Gateway for Terminal Servlets using
WebSphere ® Application Server for Windows
v Client security configuration
v Configuring CICS Transaction Gateway for WebSphere 4.01 using J2EE
v Configuring CICS Transaction Gateway 4.02 for WebSphere Application
Server on z/OS using J2EE
As more sample configuration documents become available, you can
download them from our Web site at:
www.ibm.com/software/ts/cics/
and follow the Download link.
210 CICS Transaction Gateway: Programming Guide

Redbooks
Other Useful Books
The following International Technical Support Organization (ITSO) Redbook
publication contains many examples of client/server configurations:
v CICS Transaction Gateway V3.1 The WebSphere Connector for CICS, SG24-6133
This book supersedes the following book:
v Revealed! CICS Transaction Gateway with more CICS Clients Unmasked,
SG24-5277.
v Java Connectors for CICS: Featuring the J2EE Connector Architecture, SG24-6401.
This book provides information on developing J2EE applications.
See also:
v Securing Web Access to CICS, SG24–5756.
v Workload Management for Web Access to CICS, SG24–6118.
You can obtain ITSO Redbooks from a number of sources. For the latest
information, see:
www.ibm.com/redbooks/
CICS Transaction Server publications
Other publications
CICS interproduct communication
The following books describe the intercommunication facilities of the CICS
server products:
CICS Family: Interproduct Communication, SC34-6030
Transaction Server for Windows NT: Intercommunication, SC33-1882
CICS Transaction Server for z/OS: Intercommunication Guide, SC34-6005
CICS Transaction Server for VSE/ESA : Intercommunication Guide, SC33-1665
CICS for OS/400 ® : Intercommunication, SC33-1388
TXSeries: CICS Intercommunication Guide, SC09-3900
CICS for OS/2: Intercommunication, SC33-1583
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:
Transaction Server for Windows NT: Problem Determination, GC33-1883
CICS Transaction Server for z/OS ® Problem Determination Guide, SC34-6002
The product library and related literature 211

Other publications
CICS Transaction Server for VSE/ESA Problem Determination Guide,
GC33-1663
CICS for OS/400 ® : Problem Determination, SC33-1384
TXSeries: CICS Problem Determination Guide, SC33-1565.
You can find information on CICS products at the following Web site:
www.ibm.com/software/ts/cics/
Microsoft ® Windows Family publications
The following book provides introductory material about the Windows Family
of operating systems:
v Windows NT System Guide
APPC-related publications
The following books are concerned with products providing APPC support:
IBM products
IBM Communications Server for Windows NT and Windows 2000:
Communications Server for Windows: Quick Beginnings, GC31-8424
IBM Communications Server for AIX for AIX:
IBM Communications Server for AIX: Quick Beginnings, GC31-8583
IBM Communications Server for AIX: General Information, GC31-8584
IBM Communications Server for AIX: Administration, SC31-8586
IBM Communications Server for AIX: Administration Command Reference,
SC31-8587
IBM eNetwork Personal Communications:
IBM Personal Communications for Windows NT: Quick Beginnings,
GC31-8679-02
IBM Personal Communications: Administrator’s Reference, SC31-8840
Microsoft products
Microsoft SNA Server Installation Guide
Microsoft SNA Server Administration Guide
Microsoft SNA Server Reference
Systems Network Architecture (SNA)
SNA Formats, GA27-3136
Systems Network Architecture Technical Overview, GC30-3073
212 CICS Transaction Gateway: Programming Guide

TCP62–related publications
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
GC31–7073
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074
Obtaining books from IBM
For information on books you can download, visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link.
You can order hardcopy books:
v Through your IBM representative or the IBM branch office serving your
locality.
v By calling 1-800-879-2755 in the United States.
v From the Web site at:
www.ibm.com/shop/publications/order
Other publications
The product library and related literature 213

214 CICS Transaction Gateway: Programming Guide

|
|
|
|
|
|
|
|
|
|
Accessibility
The English version of the CICS Transaction Gateway has been tested for
accessibility on the Windows operating system. The product is accessible.
Documentation
Download the CICS Information Center for an html version of the
documentation. Go to this Web page
www.ibm.com/software/ts/cics/
and follow the Library link.
© Copyright IBM Corp. 2002 215

216 CICS Transaction Gateway: Programming Guide

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.
A
abend. The termination of a task, job, or
subsystem because of an error condition that
recovery facilities cannot resolve.
APAR. (Authorized program analysis report.) A
report on the basis of which IBM supplies a fix
of a temporary corrective nature to elements of
function SYSMODs. APAR fixes are called
″corrective″ service because they are installed to
cure problems currently being experienced by an
installation. The APAR fix is usually in the form
of either a modification to a load module or an
update to card-image data. It is intended as a
temporary arrangement until a preventive service
(PTF) is issued to fix the problem permanently.
This PTF supersedes the APAR fix, and indeed
specifies this relationship on its ++VER
statement.
API. Application programming interface.
APING. A command used to verify an APPC
link.
APPC. Advanced program-to-program
communication. 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.
applet. A Java program that is downloaded to,
and executed on, a Web browser or network
computer. See also servlet.
applid. In CICS, a system initialization and
terminal control parameter that identifies the
CICS system to other remote systems.
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 facility that enables terminal
definitions to be created automatically in a CICS
server on request. The definition is deleted when
the client terminal is logged off.
automatic transaction initiation (ATI). The
process whereby a transaction request made
internally within a CICS system or network leads
to the scheduling of the transaction. An ATI
request from a CICS Transaction Gateway can
cause the initiation of a transaction in a CICS
server system.
B
beans. See JavaBeans .
BIND. 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.
C
CA. See certification authority.
CEDA. A CICS transaction that defines
resources online.
© Copyright IBM Corp. 2002 217

Glossary
certification authority. In computer security, an
organization that issues certificates. The
certification 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 External Call Interface (EXCI). An
application programming interface that enables a
program running on Z/OS, such as CICS
Transaction Gateway, to call a program running
in a CICS region. The programs can transfer data
between each other using a communication area.
Compare with External Call Interface (ECI).
CICS Gateway for Java. In CICS Universal
Clients Version 2, an interface between a Java
program and CICS that allows a Java-enabled
browser to dynamically download a Java Applet
and transparently access CICS data. This has
been replaced by the CICS Transaction Gateway.
CICS on open systems. A term used to refer
generically to the products: CICS for HP-UX,
CICS for Sun Solaris, TXSeries for AIX,
TXSeries for HP-UX, and TXSeries for Solaris.
CICS on System/390 ® . A term used to refer
generically to the products CICS Transaction
Server for z/OS , CICS for MVS/ESA ,CICS
Transaction Server for z/OS, CICS Transaction
Server for VSE/ESA, and CICS/VSE ® .
cicscli. A command that starts and stops the
Client daemon, checks the availability of servers,
and sets other options.
cicsprnt. A command that allows you to define
a printer terminal on the Client daemon
workstation. The command enables CICS
applications running on the server to direct
output to the client-attached printer.
cicsterm. A command that provides 3270
emulation and enables connection to a CICS
region.
218 CICS Transaction Gateway: Programming Guide
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. An environment variable that tells
the JVM and other Java applications where to
find the class libraries, including user-defined
class libraries.
Client API. On distributed platforms running
non-Java applications, the interface between the
Client application and the Client daemon.
client application. A user application, written in
a supported programming language other than
Java, that communicates directly with the Client
daemon.
Client daemon. The Client daemon (process
cclclnt) exists only on distributed platforms. 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. A distributed application design
model, in which the client sends a request to its
partner, the server, which executes the request
and returns the results to the client. This design
model is associated typically with cooperative
processing.
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. File CICSCOL.INI used by
the CICS Transaction Gateway to customize the
3270 screen color attributes on client
workstations.
COMMAREA. A communication area that is
used for passing data both between programs
within a transaction and between transactions.

Common Object Request Broker Architecture
(CORBA). An industry standard for an interface
definition language that enables different object
request brokers to interoperate.
configuration file. The file CTG.INI containing
information telling CICS Transaction Gateway
about the CICS servers that it can connect to, and
the communication protocols to use.
configuration tool. A graphical user interface
that allows you to configure the CICS
Transaction Gateway.
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.
control table. In CICS, a storage area used to
describe or define the configuration or operation
of the system.
conversation. The communication between a
CICS Transaction Gateway and a CICS server. In
APPC, a connection between two transaction
programs over an LU-LU session that allows
them to communicate with each other while
processing a transaction. See also session.
conversation security. In APPC, a process that
allows validation of a user ID or group ID and
password before establishing a connection.
cooperative processing. A subset of distributed
processing, in which at least the user interface
(presentation) aspect of the application runs on a
programmable workstation.
CORBA. See Common Object Request Broker
Architecture.
ctgstart. A command that starts the gateway
daemon.
D
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.
Glossary
dependent LU. A logical unit (LU) that can
receive, but not send a BIND, and which
supports only single sessions. See BIND.
digital certificate. A form of personal
identification that can be verified electronically.
Only the certificate owner who holds the
corresponding private key can present a
certificate for authentication through a Web
browser session. Anyone can verify that the
certificate is valid by using a readily available
public key.
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. A link that enables
an application program running on one CICS
system to link to another application program
running in another CICS system.
Glossary 219

Glossary
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.
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.
E
EBCDIC. Extended binary-coded decimal
interchange code. A coded character set of 256
8-bit characters developed for the representation
of textual data.
ECI. See external call interface.
emulator, 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. In the CICS Transaction
Gateway the terminal emulation function allows
client workstations to run CICS transactions that
use 3270 data flows.
220 CICS Transaction Gateway: Programming Guide
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.
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 10–megabit or 100–megabit
baseband 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 CICS External Call Interface.
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.
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.
F
firewall. A configuration of software that
prevents unauthorized traffic between a trusted
network and an untrusted network.

G
gateway. A device that connects two dissimilar
LANs, or that connects a LAN to a wide area
network (WAN), midrange computer, or
mainframe computer. A gateway device has its
own processor and memory and may perform
protocol conversion. A gateway handles multiple
communication sessions simultaneously.
gateway classes. The interface for Java Client
applications to connect to the Gateway daemon.
The Gateway classes, which are supplied with
the CICS Transaction Gateway, must be in the
classpath for Java Client applications to run.
gateway daemon. Used only in remote mode,
the Gateway daemon listens on protocols defined
in CTG.INI for gateway requests from remote
Java client applications. It issues these requests to
the Client daemon on distributed platforms, and
directly to CICS over the EXCI on z/OS. The
Gateway daemon runs the protocol listener
threads, the worker threads and the connection
manager threads. It uses the GATEWAY section
of CTG.INI (and on z/OS the ctgenvvar script)
for its configuration.
H
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 in an internet.
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
domain name of a host.
HTTP. In the Internet suite of protocols, the
protocol that is used to transfer and display
hypertext and XML documents.
HTTPS. A TCP/IP protocol that World Wide
Web servers and Web browsers use to transfer
and display documents secured by SSL.
I
iKeyman. A tool supplied with the Gateway for
maintaining digital certificates for SSLight and
JSSE.
independent LU. A logical unit (LU) that can
both send and receive a BIND, and which
supports single, parallel, and multiple sessions.
See BIND.
internet. A collection of networks
interconnected by a set of routers that allow
them to function as a single, large network.
Contrast with Internet.
Internet. The internet administered by the
Internet Architecture Board (IAB), consisting of
large national backbone networks and many
regional and campus networks all over the
world. The Internet uses the Internet suite of
protocols.
Internet address. See IP address.
Glossary
Internet Architecture Board. The technical body
that oversees the development of the internet
suite of protocols known as TCP/IP.
Internet Packet Exchange (IPX). In Novell
NetWare LANs, a communication protocol that
sends data packets to requested destinations.
Internet Protocol (IP). In TCP/IP, a protocol
that routes data from its source to its destination
in an Internet environment.
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.
intranet. A private network that integrates
Internet standards and applications (such as Web
browsers) with an organization’s existing
Glossary 221

Glossary
computer networking infrastructure. Compare
with Internet and internet.
IP. Internet Protocol.
IPX. Internet Packet Exchange.
J
J2EE. (Java 2 Platform, Enterprise Edition.) 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.
Java. An object-oriented programming language
for portable interpretive code that supports
interaction among remote objects.
JavaBeans. A platform-independent, software
component technology for building reusable Java
components called beans. Once built, these beans
can be made available for use by other software
engineers or they can be used in Java
applications. Also, using JavaBeans, software
engineers can manipulate and assemble beans in
a graphical drag-and-drop development
environment.
Java client application. A Java application,
servlet or applet that communicates with the
Gateway classes.
Java development kit (JDK). A software
package that can be used to write, compile,
debug, and run Java applets and applications.
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 Secure Socket Extension (JSSE). An
implementation of SSL, written in Java, and
supported by CICS Transaction Gateway.
222 CICS Transaction Gateway: Programming Guide
Java Virtual Machine (JVM). A software
implementation of a processor that runs
compiled Java code (applets and applications).
JDK. See Java development kit (JDK).
JNI. See Java Native Interface (JNI).
JSSE. See Java Secure Socket Extension (JSSE).
JVM. See Java Virtual Machine (JVM).
K
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. The default keyboard mapping file for
the CICS Transaction Gateway is CICSKEY.INI.
KeyRing or KeyStore. In computer security, a
file that contains public keys, private keys,
trusted roots, and certificates.
L
LAN. See local area network.
local area network (LAN). A network of
workstations, or terminals, or both, where all the
connected systems are relatively near to each
other. See wide area network.
local mode. Describes a Java Client application
using the Gateway local protocol. The Gateway
daemon is not used in local mode; on distributed
platforms, the Gateway classes interface directly
with the Client daemon API, and with the EXCI
on z/OS. See remote mode.
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.
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.
LU-LU session type 6.2. In SNA, a type of
session for communication between peer
systems. Synonymous with APPC protocol.
LU 6.2. See APPC.
M
MAC. Medium access control.
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.
N
name server. In TCP/IP, synonym for Domain
Name Server In Internet communications, the
host that translates host names into their
respective internet addresses when requested by
the hosts on the network A physical device, and
its associated software, that enables a processor
or controller to be connected to a network.
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.
O
object. In object-oriented programming, a
concrete realization of a class that consists of
data and the operations associated with that
data.
object request broker (ORB). Software that
serves as an intermediary by transparently
enabling objects to exchange requests and
responses.
OO. Object-oriented.
P
Glossary
pacing. A technique by which a receiving
station controls the rate of transmission of a
sending station to prevent overrun.
packet internet groper (PING). In Internet
communications, a program used in TCP/IP
networks to test the ability to reach destinations
Glossary 223

Glossary
by sending the destinations an Internet Control
Message Protocol (ICMP) echo request and
waiting for a reply.
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. Packet internet groper. The command
that sends an ICMP Echo Request packet to a
gateway, router, or host with the expectation of
receiving 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. Primary logical unit. 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.
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 (LU) that contains the primary half-session
for a particular LU-LU session. Contrast with
secondary logical unit. See also logical unit.
Note: A particular logical unit may contain
primary and secondary half-sessions for
different active LU-LU sessions.
protocol boundary. The signals and rules
governing interactions between two components
within a node.
224 CICS Transaction Gateway: Programming Guide
R
RACF. Resource Access Control Facility. An IBM
licensed program that provides access control by
identifying users to the system; verifying users of
the system; authorizing access to protected
resources; logging detected, unauthorized
attempts to enter the system; and logging
detected accesses to protected resources.
region. A physical instance of a CICS server.
remote mode. Describes a Java Client
application using a Gateway network protocol to
connect to the Gateway daemon. See local mode.
remote procedure call (RPC). Remote procedure
calls are analogous to the standard procedure
calls used in modern programming, providing
modularity and reducing code size. The main
difference between standard procedure calls and
remote procedure calls is that in a remote
procedure call, the called procedure is being
executed by a different process than the caller. To
the calling procedure, a remote procedure call
looks the same as a call to a local procedure.
When a program makes a remote procedure call
to a remote application, the procedure’s
parameters are automatically bundled into a
request message, which is then sent to the
remote program or system.
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.
RU. Request unit. Response unit.

RPC. See remote procedure call.
S
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.
servlet. A Java servlets program that run on a
Web server machine, unlike Java applets, which
are downloaded to a Web browser. Java servlets
have become popular as a replacement for CGI
(Common Gateway Interface) programs.
session. In SNA, a logical connection between
two network addressable units (NAUs) that can
be activated, tailored to provide various
protocols, and deactivated as requested. The
session activation request and response can
determine options for such things as rate and
concurrency of data exchange, control of
contention and error recovery, and characteristics
of the data stream. Sessions compete for network
resources, such as links within the path control
network. For routing purposes, each session is
identified by the network or local addresses of
the session partners. See LU-LU session, LU-LU
session type.
session limit. In SNA, the maximum number of
concurrently active LU-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.
signon capable terminal. A signon capable
terminal allows signon transactions, either
CICS-supplied (CESN) or user-written, to be run.
Contrast with signon incapable terminal.
SIT (system initialization table). A table
containing parameters used to start a CICS
control region.
SNA gateway. A gateway that handles multiple
APPC communication sessions simultaneously.
See gateway.
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.
SSL. See Secure Sockets Layer (SSL).
Glossary
SSLight. An implementation of SSL, written in
Java, and supported by CICS Transaction
Gateway.
System Management Interface Tool (SMIT). In
the AIX operating system, a set of menu-driven
services that facilitate the performance of system
tasks such as installation, management,
configuration, and diagnosis.
standard error. In many workstation-based
operating systems, the output stream to which
error messages or diagnostic messages are sent.
subnet. In TCP/IP, a part of a network that is
identified by a portion of the Internet address.
Synonym for subnetwork.
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.
Systems Network Architecture (SNA). The
description of the logical structure, formats,
protocols, and operational sequences for
Glossary 225

Glossary
transmitting information units through, and
controlling the configuration and operation of,
networks.
System SSL. An implementation of SSL,
supported by CICS Transaction Gateway on
z/OS. Written in native code, it supports
hardware encryption technology available to
z/OS, and can be used only for SSL servers on
that operating system.
T
Taskguide. A function of the configuration tool
that provides step-by-step guidance to
configuring your CICS Transaction Gateway. .
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. Transmission Control Protocol/Internet
Protocol.
TCP/IP address. An address that uniquely
identifies a machine on a network. A machine
can have several threads of execution running at
the same time; a TCP/IP port uniquely identifies
a particular thread.
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.
Terminal Servlet. A Java program that allows
you to use a Web browser as an emulator for a
3270 CICS application running on any CICS
server.
thread. A stream of computer instructions that
is in control of a process. A multithread process
begins with one stream of instructions (one
thread) and may later create other instruction
streams to perform tasks.
226 CICS Transaction Gateway: Programming Guide
token ring. A network with a ring topology that
passes tokens from one attaching device to
another; for example, the IBM Token-Ring
network.
trace. A record of data that provides a history of
events that occurred in a system. The process of
recording the sequence in which the statements
in a program are executed and, optionally, are
the values of the program variables used in the
statements.
transaction program. A program that uses the
APPC application program interface (API) to
communicate with a partner application program
in the same node or at a partner node.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A set of communications protocols
that support peer-to-peer connectivity functions
for both local and wide area networks. TCP/IP
can be used for client/server links between the
Client daemon and, for example, CICS for
OS/2 ® , CICS for Windows NT.
type 2.0 node. An SNA node that attaches to a
subarea network as a peripheral node and
provides full 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.
U
URL. (Uniform Resource Locator.) 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.
user session. Any APPC session other than a
SNASVCMG session.

V
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.
W
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.
Glossary
Glossary 227

Glossary
228 CICS Transaction Gateway: Programming Guide

Index
Special characters
ix
Numerics
3270 datastreams 60, 150
A
accessibility 215
accessing fields on 3270 screens 94
Accessing fields on CICS 3270 screens
in C++ External presentation interface 63
Using the CICS Transaction Gateway C++
classes 63
AID 123
Apartments
Creating COM Objects 138
application transaction demarcation 120
Async Exception Handling 48
Asynchronous call synchronisation
in ATI 62
asynchronous calls 4
Asynchronous reply handling
in C++ External call interface 55
in Controlling server interactions 55
asynchronous sends 94
ATI 61, 155
ATTRIBUTE_BACKGROUNDCOLOR 123
ATTRIBUTE_BASE 123
ATTRIBUTE_FOREGROUNDCOLOR 123
ATTRIBUTE_HIGHLIGHT 123
ATTRIBUTE_MARKER 123
ATTRIBUTE_NONE 123
ATTRIBUTE_TRANSPARENCY 123
autoinstall 21
Automatic Transaction Initiation 61, 155
automation compatible 137
B
backout
in Managing logical units of work 58
in Server connection 51
Backout
in ECI Link Calls within a Unit Of Work 148
Basic Mapping Support
in C++ External presentation interface 59
BMS
map source files 60
utility 60
BMS Map Conversion utility 100, 107
BMS paging 19
BMSMapConvert 107
books 209
CICS Transaction Gateway 209
business object 145
C
C++ External call interface
Asynchronous reply handling 55
Controlling server interactions 53
Deferred synchronous reply handling 56
Finding potential servers 50
Managing logical units of work 57
Monitoring server availability 51
Passing data to a server program 52
Server connection 50
Synchronous reply handling 54
C++ External presentation interface
Accessing fields on CICS 3270 screens 63
EPI BMS conversion utility 67
EPI call synchronization types 64
Mapset containing a single map 69
Starting a 3270 terminal connection to CICS 62
Using EPI BMS Map Classes 70
Using the CICS Transaction Gateway C++
classes 59
callback routine
EPI 25, 26
cancel
in Monitoring server availability 51
in Server connection 51
CCF 79
ccf2.jar 129
CCI
framework classes 115
input and output classes 116
Ccl Field
in Running a CICS 3270 session 151
Ccl Map
Using BMS Map data with EPI COM classes 155
Ccl::async
in EPI call synchronization types 65
Ccl::dsync
in EPI call synchronization types 66
Ccl::sync
in EPI call synchronization types 64
CclBuf
in Passing data to a server program 52
CclConn
in Monitoring server availability 51
© Copyright IBM Corp. 2002 229

CclConn (continued)
in Server connection 50
cclDSync
in ECI Call Synchronization Types 146
in EPI call synchronization types 152
CclECI
Finding potential servers 50
CclField
in Accessing fields on CICS 3270 screens 64
in C++ External presentation interface 61
CclFlow
in Controlling server interactions 53
CclMap
in C++ External presentation interface 61
in EPI BMS conversion utility 68
in Mapset containing a single map 69
CCLOECI.EXE
in Using the COM classes 139
CCLOEPI.EXE
in Using the COM classes 139
CclScreen 62
in C++ External presentation interface 61
in EPI BMS conversion utility 69
CclSecAttr 58, 72
CclSession 62
in C++ External presentation interface 61
in EPI call synchronization types 65
CclSession::client
in EPI call synchronization types 65
CclSession::idle
in EPI call synchronization types 65
CclSession::server
in EPI call synchronization types 65
cclSync
in ECI Call Synchronization Types 146
in EPI call synchronization types 152
CclTerminal 61, 62
in C++ External presentation interface 61
CclUOW
in Managing logical units of work 57
changed
in Monitoring server availability 51
in Server connection 51
changePassword 58, 71
CICS Server Information
in Connecting to CICS 3270 applications using the
EPI
in Using the COM classes 153
CICS Server Information and Connection Status
in Making an ECI link call to CICS
in Using the COM classes 147
CICS Transaction Gateway initialisation file
in Finding potential servers 50
CICS Transaction Gateway initialization file
in Starting a 3270 terminal connection to CICS 63
230 CICS Transaction Gateway: Programming Guide
CICS_EciDataReturnExit 182
CICS_EciDataSendExit 181
CICS_EciExitInit entry point 169
CICS_EciExternalCallExit1 176
CICS_EciExternalCallExit2 178
CICS_EciInitializeExit 174
CICS_EciListSystems function 10
CICS_EciSetProgramAliasExit 183
CICS_EciSystemIdExit 179
CICS_EciTerminateExit 175
CICS_EPI_EVENT_ADD_TERM event
use 26
CICS_EPI_EVENT_CONVERSE event
use 26, 27, 33
CICS_EPI_EVENT_END_TERM event
use 26
CICS_EPI_EVENT_END_TRAN event
use 26
CICS_EPI_EVENT_SEND event
use 26, 27, 32
CICS_EPI_EVENT_START_ATI event
use 26
CICS_EPI_NOWAIT 25
CICS_EPI_WAIT 25
CICS_EpiAddExTerminal function
use 20, 25
CICS_EpiAddTerminal function
use 20, 25
CICS_EpiAddTerminalExit 188
CICS_EpiDelTerminal function
use 23
CICS_EpiDelTerminalExit 196
CICS_EpiEventData_t data structure
use 25, 26
CICS_EpiExitInit entry point 169
CICS_EpiGetEvent function
use 25, 26
CICS_EpiGetEventExit 197
CICS_EpiInitialize function
use 20
CICS_EpiInitializeExit 186
CICS_EpiListSystems function
use 20, 42
CICS_EpiPurgeTerminal function
use 23
CICS_EpiReply function
use 27, 31
CICS_EpiReplyExit 195
CICS_EpiStartTran function
use 24, 26, 27, 31
CICS_EpiStartTranExit 193
CICS_EpiSystem_t data structure
use 42
CICS_EpiSystemIdExit 199
CICS_EpiTermIdExit 191

CICS_EpiTermIdInfoExit 192
CICS_EpiTerminate function
use 20
CICS_EpiTerminateExit 187
CICS_EpiTranFailedExit 201
CICS_EXIT_BAD_ANCHOR return code
CICS_EciDataReturnExit 182
CICS_EciDataSendExit 181
CICS_EciExternalCallExit1 176
CICS_EciExternalCallExit2 178
CICS_EciSetProgramAliasExit 183
CICS_EciSystemIdExit 180
CICS_EciTerminateExit 175
CICS_EpiAddTerminalExit 189
CICS_EpiDelTerminalExit 196
CICS_EpiGetEventExit 197
CICS_EpiReplyExit 195
CICS_EpiStartTranExit 193
CICS_EpiSystemIdExit 200
CICS_EpiTermIdExit 191
CICS_EpiTermIdInfoExit 192
CICS_EpiTerminateExit 187
CICS_EpiTranFailedExit 201
CICS_EXIT_BAD_PARM return code
CICS_EciDataReturnExit 182
CICS_EciDataSendExit 181
CICS_EciExternalCallExit1 176
CICS_EciExternalCallExit2 178
CICS_EciSetProgramAliasExit 183
CICS_EciSystemIdExit 180
CICS_EpiAddTerminalExit 189
CICS_EpiDelTerminalExit 196
CICS_EpiGetEventExit 197
CICS_EpiReplyExit 195
CICS_EpiStartTranExit 193
CICS_EpiSystemIdExit 200
CICS_EpiTermIdExit 191
CICS_EpiTermIdInfoExit 192
CICS_EpiTranFailedExit 202
CICS_EXIT_BAD_STORAGE return code
CICS_EciTerminateExit 175
CICS_EpiTerminateExit 187
CICS_EXIT_CANT_INIT_EXITS return code
CICS_EciInitializeExit 174
CICS_EpiInitializeExit 186
CICS_EXIT_DONT_ADD_TERMINAL return code
CICS_EpiAddTerminalExit 189
CICS_EpiSystemIdExit 200
CICS_EXIT_GIVE_UP return code
CICS_EciSystemIdExit 180
CICS_EXIT_NO_EXIT return code
CICS_EciInitializeExit 174
CICS_EpiInitializeExit 186
CICS_EXIT_OK return code
CICS_EciDataReturnExit 182
CICS_EXIT_OK return code (continued)
CICS_EciDataSendExit 181
CICS_EciExternalCallExit1 176
CICS_EciExternalCallExit2 178
CICS_EciInitializeExit 174
CICS_EciSetProgramAliasExit 183
CICS_EciSystemIdExit 179
CICS_EciTerminateExit 175
CICS_EpiAddTerminalExit 189
CICS_EpiDelTerminalExit 196
CICS_EpiGetEventExit 197
CICS_EpiInitializeExit 186
CICS_EpiReplyExit 195
CICS_EpiStartTranExit 193
CICS_EpiSystemIdExit 200
CICS_EpiTermIdExit 191
CICS_EpiTermIdInfoExit 192
CICS_EpiTerminateExit 187
CICS_EpiTranFailedExit 201
CICS_ExternalCall 10
CICS3270.INC include file 30
CICSCLI
in Starting a 3270 terminal connection to CICS 63
cicseci.hpp
Using the C++ classes 47
CICSECIX 169
CICSELUW flag 79
cicsepi.hpp
Using the C++ classes 47
CICSEPIEXITINIT function 203
CICSEPIX 169
cicsepix.dll 203
cicsj2ee.jar 129
CICSPRNT 203
CICSTERM 203
CLASSPATH 101
CLASSPATH environment variable 81
client
in EPI call synchronization types 66
closing an EPIInteraction 124
com.ibm.ctg.client.T class 82
COMMAREA 49
CommareaLength 119
commit
in Managing logical units of work 58
in Server connection 51
Commit
in ECI Link Calls within a Unit Of Work 148
Common Client Interface 115
Common Client Interface (CCI) 115
Common Connector Framework 79
communication, synchronous 54
compiling applications 129
Component Object Model
in Establishing the working environment 137
Index 231

Connect
in CICS Server Information and Connection
Status 147
Connect.Link
in ECI Call Synchronization Types 146
in ECI Link Calls within a Unit Of Work 148
Connecting to CICS 3270 applications using the EPI
CICS Server Information 153
EPI call synchronization types 152
in Using the COM classes 150
Running a CICS 3270 session 151
Using BMS Map data with EPI COM classes 153
Connection object 58
ConnectionFactory object
creating 130
storing 131
connector.jar 129
Controlling server interactions
Asynchronous reply handling 55
Deferred synchronous reply handling 56
in C++ External call interface 53
Synchronous reply handling 54
Using the CICS Transaction Gateway C++
classes 53
CreateObject
in Connecting to CICS 3270 applications using the
EPI 151
in Making an ECI link call to CICS using
VBScript 146
ctgclient.jar 81, 102, 129
ctgsamples.jar 101
ctgserver.jar 81
ctgstart script 85
CursorColumn 123, 124
CursorRow 123, 124
D
Data parameter
CICS_EpiStartTran function 24
DBCS 19, 60, 150
default exception handler 48
Deferred synchronous
in ATI support 156
Deferred synchronous call synchronisation
in ATI 62
Deferred synchronous reply handling
in C++ External call interface 56
in Controlling server interactions 56
Delphi 137
Details
in Making an ECI link call to CICS 145
DeviceType 122
disability 215
disconnect
in EPI call synchronization types 66
232 CICS Transaction Gateway: Programming Guide
disconnecting terminals 99
distributed program link 4
distributed program link (DPL) 9
distributed transaction processing 4
documentation 209
DPL 9
E
ECI 9
in CICS Server Information and Connection
Status 147
ECI (External Call Interface) 3
ECI Call Synchronization Types
in Making an ECI link call to CICS
in Using the COM interfaces 146
ECI connection interfaces 117
ECI exits 171
ECI interaction interfaces 118
ECI Link Calls within a Unit Of Work
in Making an ECI link call to CICS
in Using the COM interfaces 148
ECI parameter block 10, 40, 163
ECI resource adapter
CCI 117
ECI status block 15
ECI_ASYNC_NOTIFY_MSG call type
definition 161
use 163, 164
ECI_ASYNC_NOTIFY_SEM call type
definition 162
use 163
eci_async_notify.sem_handle 162, 163
eci_async_notify.window_handle 162
eci_call_type 10
ECI_ERR_NULL_MESSAGE_ID 164
ECI_ERR_NULL_SEM_HANDLE 164
ECI_ERR_NULL_WIN_HANDLE 164
eci_extend_mode 13, 16
ECI_GET_REPLY call type
use 161, 162, 163
ECI_GET_SPECIFIC_REPLY call type
use 161, 162, 163
eci_luw_token 12, 13, 14, 16
eci_message_id 162, 164
eci_message_qualifier 11
with ECI_ASYNC_NOTIFY_MSG call type 162
with ECI_ASYNC_NOTIFY_SEM call type 162
with ECI_STATE_ASYNC_MSG call type 162
with ECI_STATE_ASYNC_SEM call type 163
eci_program_name 13
ECI_STATE_ASYNC_MSG call type
definition 162
use 163, 164
ECI_STATE_ASYNC_SEM call type
definition 162

ECI_STATE_ASYNC_SEM call type (continued)
use 163
eci_window_handle 163
ECIConnectionSpec 117
ECIInteractionSpec 118
ECIRequest 78
environment variables 45
EPI 19
3270 data streams 30
3270 order codes 33
in CICS Server Information 153
EPI (External Call Interface) 4
EPI beans 101
EPI BMS conversion utility
in C++ External presentation interface 67
Mapset containing a single map 69
using the CICS Transaction Gateway C++
classes 67
EPI call synchronization types
in C++ External presentation interface 64
in Connecting to CICS 3270 applications using the
EPI
in Using the COM classes 152
Using the CICS Transaction Gateway C++
classes 64
EPI connection interfaces 122
EPI exits 184
EPI interaction interfaces 122
EPI Java Beans
EPITerminal 102, 108
screen handler beans 106
using 102
EPI resource adapter
CCI 121
EPI Screen Record 125
EPI support classes 87
accessing fields 94
asynchronous sends 94
disconnecting terminals 99
establishing terminals 90
exception handling 97
handleException method 97
handleReply method 95
overview 87
sessions 94
synchronous sends 94
terminal encoding 99
using 90
using send 93
EPIBasicScreenHandler 101
EPIConnectionSpec 122
EPIFieldRecord 126
EPIGateway class 90
EPIInteraction, closing 124
EPIInteractionSpec 122
EPIMonitor 101
EPIRequest class 79
EPIScreenButtons 101
Err objects 142
ErrorWindow 142
ESI
benefits 36
overview 35
ESI (External Security Interface) 5, 35
exception handler, default 48
exception handling 141
Exception Handling, Async 48
exceptions 97
exceptions, handling 47
EXCI programming considerations 86
ExCode 142
ExCodeText 142
EXEC CICS CONVERSE 27
EXEC CICS LINK 9
EXEC CICS RECEIVE 27, 31, 32, 33
EXEC CICS RECEIVE BUFFER 33
EXEC CICS RECEIVE MAP 31, 32
EXEC CICS RETURN
TRANSID option 27
EXEC CICS SEND 27, 31
EXEC CICS SEND MAP 31
EXEC CICS START
DELAY option 20
ExecuteTimeout 119
extended calls 4
External call interface
Using the CICS Transaction Gateway C++
classes 49
External Call Interface (ECI) 3
External Call Interface (EPI) 4
External Security Interface (ESI) 5, 35
F
field
in Mapset containing a single map 69
field()
in Mapset containing a single map 69
FieldByIndex
Using BMS Map data with EPI COM classes 155
FieldByPosition
Using BMS Map data with EPI COM classes 155
Finding potential servers
in C++ External call interface 50
Using the CICS Transaction Gateway C++
classes 50
Flow
in CICS Server Information and Connection
Status 147
Index 233

Form_Load
in Connecting to CICS 3270 applications using the
EPI 151
in Making an ECI link call to CICS 145
framework classes 115
front end programming interface 4
FunctionName 118, 123
G
glossary of terms and abbreviations 217
H
handleException 48
handleException method 97
handleReply 62
in EPI call synchronization types 65, 66, 67
using EPI BMS Map Classes 71
handleReply method 95
handling exceptions 47
handling screens 104
handling, exception 141
heap size 81
I
idle
in EPI call synchronization types 66
Initiation, Automatic Transaction 61
input records 124
input/output classes 115, 116
input/output records 119
install_path ix
installation
path ix
installation path ix
instance
in Finding potential servers 50
InteractionVerb 118, 122
J
J2EE Tracing 132
Java
beans, EPI 101
client programs 74
heap size 81
samples 101
stack size 81
Java 2 Security Manager 113
Java permissions 113
JavaGateway 76
flowing requests 78
protocols 76
security 76
SSL 77
JNDI 131
JSSE 73, 111, 113
234 CICS Transaction Gateway: Programming Guide
L
link
in Server connection 51
Link
in Making an ECI link call to CICS 145
load balancing 203
logical unit of work 12
LogonLogoff classes 127
M
Making an ECI link call to CICS
CICS Server Information and Connection
Status 147
ECI Call Synchronization Types 146
ECI Link Calls within a Unit Of Work 148
in Using the COM classes 144
making ECI calls on z/OS 84
CICS security considerations 85
program link calls 84
status information calls 85
making EPI calls on z/OS 86
managed environment 120
Managing logical units of work
in C++ External call interface 57
Using the CICS Transaction Gateway C++
classes 57
Map
in Using BMS Map data with EPI COM
classes 153, 154
Map.FieldByName
in Using BMS Map data with EPI COM classes 155
Map.Validate
in Using BMS Map data with EPI COM classes 155
MAPINQ1Map
in Mapset containing a single map 69
MapName 124
Mapset containing a single map
in C++ External presentation interface 69
in EPI BMS conversion utility 69
MapSetName 124
Monitoring server availability
in C++ External call interface 51
Using the CICS Transaction Gateway C++
classes 51
multi-threading 47
N
NetName 122
New
in Making an ECI link call to CICS 145
nonmanaged environment 120
running the J2EE CICS resource adapters 131
using J2EE CICS resource adapters in 130
NotifyFn parameter
CICS_EpiAddTerminal function 25

O
On Error Goto 142
On Error Resume 142
OO support 7
output records 124
OutputAttributeType 123
P
Passing data to a server program
in C++ External call interface 52
Using the CICS Transaction Gateway C++
classes 52
password 58
Password 118, 122
password expiration management (PEM) 5, 35
Password Expiry Management 149, 156
Password Expiry Management (PEM) 71
PEM (password expiration management) 5, 35
PF3
Accessing fields on CICS 3270 screens 63
poll
in Deferred synchronous reply handling 56, 57
in EPI call synchronization types 67
Poll
in ECI Call Synchronization Types 146, 147
in EPI call synchronization types 152
poll method 62
in ATI support 156
pollForReply method
in ATI support 156
program link calls 12
programming
EPI programming 87
EPI support classes 88
Java classes 73
Java client programs 74
programming interface 73
Programming Overview
in Using the COM interfaces 141
publications, CICS Transaction Gateway 209
Q
queryATI 61, 156
R
receiveATI 62
receiveATI method
in ATI support 156
Registration 137
reply handling, asynchronous 55
ReplyLength 119
resource adapter samples 133
ECI 133
EPI 134
Running a CICS 3270 session
in Connecting to CICS 3270 applications using the
EPI
in Using the COM classes 151
S
sample programs 167
samples, Java 101
Samples.txt 167
screen
Accessing fields on CICS 3270 screens 63
Screen
in Running a CICS 3270 session 151
Using BMS Map data with EPI COM classes 155
screen handlers 104
screen size 19
screenable.jar 129
ScreenDepth 124
ScreenWidth 124
Security
Java security permissions 113
security classes 111
security considerations
ECI 15
EPI 27
security credentials 129
security exits 111
Security Management
ECI 58
EPI 71
semaphore 162
send
in EPI call synchronization types 64, 65, 66, 67
in Starting a 3270 terminal connection to CICS 63
send method
in ATI 62
in ATI support 156
server
in EPI call synchronization types 66, 67
Server connection
in C++ External call interface 50
Using the CICS Transaction Gateway C++
classes 50
serverCount
Finding potential servers 50
serverDesc
Finding potential servers 50
serverName
Finding potential servers 50
Servers 137
Session
in Running a CICS 3270 session 151
Session.SetSyncType
in EPI call synchronization types 152
setATI 61, 156
Index 235

SetErrorFormat 142
SetSyncType
in ECI Call Synchronization Types 146
signon capable 28
signon incapable 28
SSL 77
stack size 81
start method
in ATI support 156
Starting a 3270 terminal connection to CICS
in C++ External presentation interface 62
Using the CICS Transaction Gateway C++
classes 62
state
in EPI call synchronization types 67
state (parameter)
in EPI call synchronization types 65
status
in Monitoring server availability 51
in Server connection 51
stream format 127
streamable interface 119
structured fields 19
Synchronous
in ATI support 156
Synchronous call synchronisation
in ATI 62
synchronous calls 4
Synchronous reply handling
in C++ External call interface 54
in Controlling server interactions 54
synchronous sends 94
synchronous, Deferred 62
system properties, Java 82
T
TermId 124
Terminal
in Running a CICS 3270 session 151
Terminal class 156
terminal index 21, 80
terminal, signon capable 28
terminal, signon incapable 28
Terminal.Poll
in EPI call synchronization types 152
Terminal.Send
in EPI call synchronization types 152
Terminal.Start
in EPI call synchronization types 152
in Running a CICS 3270 session 151
terminals
basic 90
disconnecting 99
encoding 99
establishing to CICS 90
236 CICS Transaction Gateway: Programming Guide
terminals (continued)
extended 92
threads, multiple 47
time-out 11
tracing 82
Tracing
J2EE 132
Transaction Initiation, Automatic 61, 155
transID 62
TransId parameter
CICS_EpiStartTran function 24
U
UOW
in ECI Link Calls within a Unit Of Work 148
uowId 58
user-defined
CICS_EpiSystemIdExit 200
CICS_EpiTerminateExit 187
user-defined return code
CICS_EciDataReturnExit 182
CICS_EciDataSendExit 181
CICS_EciExternalCallExit1 176
CICS_EciExternalCallExit2 178
CICS_EciInitializeExit 174
CICS_EciSetProgramAliasExit 183
CICS_EciSystemIdExit 180
CICS_EciTerminateExit 175
CICS_EpiAddTerminalExit 189
CICS_EpiDelTerminalExit 196
CICS_EpiGetEventExit 197
CICS_EpiInitializeExit 186
CICS_EpiReplyExit 195
CICS_EpiStartTranExit 193
CICS_EpiTermIdExit 191
CICS_EpiTermIdInfoExit 192
CICS_EpiTranFailedExit 202
UserName 118, 122
Using BMS Map data with EPI COM classes
in Connecting to CICS 3270 applications using the
EPI
in Using the COM classes 153
Using EPI BMS Map Classes
in C++ External presentation interface 70
Using the CICS Transaction Gateway C++
classes 70
Using the CICS Transaction Gateway C++ classes
Accessing fields on CICS 3270 screens 63
Controlling server interactions 53
EPI BMS conversion utility 67
EPI call synchronization types 64
Finding potential servers 50
Managing logical units of work 57
Monitoring server availability 51
Passing data to a server program 52

Using the CICS Transaction Gateway C++ classes
(continued)
Server connection 50
Starting a 3270 terminal connection to CICS 62
Using EPI BMS Map Classes 70
Using the COM classes
Connecting to CICS 3270 applications using the EPI
CICS Server Information 153
EPI call synchronization types 152
Running a CICS 3270 session 151
Using BMS Map data with EPI COM
classes 153
Making an ECI link call to CICS
CICS Server Information and Connection
Status 147
ECI Call Synchronization Types 146
ECI Link Calls within a Unit Of Work 148
V
VBScript 137
verifyPassword 58, 71
Version parameter
CICS_EpiInitialize function 29
Visual Basic 137
W
wait
in Asynchronous reply handling 56
in Deferred synchronous reply handling 57
Wait parameter
CICS_EpiGetEvent 25
Windows
environment variables 45
WorkLoad Manager 183
writing input and output records 124
Z
z/OS
ECI return codes and server errors 86
EXCI considerations 86
making ECI calls 84
making EPI calls 86
Index 237

238 CICS Transaction Gateway: Programming Guide

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.
© Copyright IBM Corp. 2002 239

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 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.
COPYRIGHT LICENSE:
This information contains sample application programs in source language,
which illustrate programming techniques on various operating platforms. You
may copy, modify, and distribute these sample programs in any form without
payment to IBM for the purposes of developing, using, marketing, or
distributing application programs conforming to IBM’s application
programming interfaces for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability,
serviceability, or function of these programs.
240 CICS Transaction Gateway: Programming Guide

Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, or other countries, or both:
AIX CICS
IBM OS/390
VisualAge
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 of Sun
Microsystems, Inc. in the United States, or other countries, or both.
Other company, product or service names may be trademarks or service
marks of others.
Notices 241

242 CICS Transaction Gateway: Programming Guide

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. 2002 243

����
Program Number: 5724-D12
Printed in U.S.A.
SC34-6141-00

Spine information:
��� CICS Transaction Gateway Programming Guide Version 5.0

CICS Transaction Gateway
Programming Reference
Version 5.0
���
SC34-6140-00

CICS Transaction Gateway
Programming Reference
Version 5.0
���
SC34-6140-00

Note!
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page 251.
First Edition (July 2002)
This edition applies to Version 5.0 of the CICS ® Transaction Gateway, program number 5724-D12. It will also apply to
all subsequent versions, releases, and modifications until otherwise indicated in new editions.
This edition replaces SC34-5946, SC34-5947, SC34-5945, SC34-5938. Vertical lines at the left side of the page indicate
material that is new to this edition.
© Copyright International Business Machines Corporation 1989, 2002. 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. . . . . . . . . . . v
Who should read this book . . . . . . . v
Conventions and terminology used in this
book . . . . . . . . . . . . . . . v
Installation path . . . . . . . . . vii
Directory delimiters . . . . . . . . vii
Programming language specific . . . . vii
Operating system specific . . . . . . vii
Summary of changes . . . . . . . . ix
Chapter 1. COM . . . . . . . . . . . 1
Buffer COM class . . . . . . . . . . 1
Interface Selection . . . . . . . . . 1
Object Creation . . . . . . . . . . 1
Methods . . . . . . . . . . . . 2
Connect COM class . . . . . . . . . . 4
Interface Selection . . . . . . . . . 4
Object Creation . . . . . . . . . . 4
Methods . . . . . . . . . . . . 4
ECI COM class . . . . . . . . . . . 10
Interface Selection . . . . . . . . . 10
Object Creation . . . . . . . . . . 10
Methods . . . . . . . . . . . . 11
EPI COM class . . . . . . . . . . . 13
Interface Selection . . . . . . . . . 13
Object Creation . . . . . . . . . . 13
Methods . . . . . . . . . . . . 13
Field COM class . . . . . . . . . . 17
Interface Selection . . . . . . . . . 17
Methods . . . . . . . . . . . . 17
Flow COM class . . . . . . . . . . 22
Interface Selection . . . . . . . . . 22
Object Creation . . . . . . . . . . 23
Methods . . . . . . . . . . . . 23
Map COM class. . . . . . . . . . . 26
Interface Selection . . . . . . . . . 26
Object Creation . . . . . . . . . . 26
Methods . . . . . . . . . . . . 26
Screen COM class . . . . . . . . . . 28
Interface Selection . . . . . . . . . 28
Methods . . . . . . . . . . . . 28
SecAttr COM class. . . . . . . . . . 30
Interface Selection . . . . . . . . . 30
Methods . . . . . . . . . . . . 31
SecTime COM class . . . . . . . . . 32
Interface Selection . . . . . . . . . 32
Methods . . . . . . . . . . . . 32
Session COM class . . . . . . . . . . 33
Interface Selection . . . . . . . . . 33
Object Creation . . . . . . . . . . 33
Methods . . . . . . . . . . . . 34
Terminal COM class . . . . . . . . . 35
Interface Selection . . . . . . . . . 35
Object Creation . . . . . . . . . . 35
Methods . . . . . . . . . . . . 36
UOW COM class . . . . . . . . . . 45
Interface Selection . . . . . . . . . 45
Object Creation . . . . . . . . . . 45
Methods . . . . . . . . . . . . 45
Chapter 2. Java . . . . . . . . . . 47
Class/interface page . . . . . . . . . 47
Use page . . . . . . . . . . . . . 48
Tree (Class Hierarchy). . . . . . . . . 48
Deprecated API . . . . . . . . . . . 48
Index page . . . . . . . . . . . . 48
Chapter 3. C++. . . . . . . . . . . 49
Ccl class . . . . . . . . . . . . . 49
Enumerations . . . . . . . . . . 49
CclBuf class . . . . . . . . . . . . 49
CclBuf constructors . . . . . . . . 50
Public methods . . . . . . . . . . 51
Enumerations . . . . . . . . . . 55
CclConn class . . . . . . . . . . . 55
CclConn constructor . . . . . . . . 56
Public methods . . . . . . . . . . 56
Enumerations . . . . . . . . . . 60
CclECI class . . . . . . . . . . . . 61
CclECI constructor (protected) . . . . . 61
Public methods . . . . . . . . . . 61
CclEPI class . . . . . . . . . . . . 63
CclEPI constructor . . . . . . . . . 63
Public methods . . . . . . . . . . 63
Enumerations . . . . . . . . . . 65
CclException class . . . . . . . . . . 66
Public methods . . . . . . . . . . 66
CclField class . . . . . . . . . . . 67
Public methods . . . . . . . . . . 67
© Copyright IBM Corp. 1989, 2002 iii

Enumerations . . . . . . . . . . 71
CclFlow class . . . . . . . . . . . 73
CclFlow constructor . . . . . . . . 73
Public methods . . . . . . . . . . 74
Enumerations . . . . . . . . . . 76
CclMap class. . . . . . . . . . . . 77
CclMap constructor . . . . . . . . 77
Public methods . . . . . . . . . . 77
Protected methods . . . . . . . . . 78
CclScreen class . . . . . . . . . . . 79
Public methods . . . . . . . . . . 79
Enumerations . . . . . . . . . . 81
CclSecAttr . . . . . . . . . . . . 82
Public Methods . . . . . . . . . . 82
CclSecTime . . . . . . . . . . . . 82
Public Methods . . . . . . . . . . 83
CclSession class . . . . . . . . . . . 84
CclSession constructor . . . . . . . 84
Public methods . . . . . . . . . . 84
Enumerations . . . . . . . . . . 85
CclTerminal class . . . . . . . . . . 86
CclTerminal constructor . . . . . . . 86
Public methods . . . . . . . . . . 88
Enumerations . . . . . . . . . . 94
CclUOW class . . . . . . . . . . . 95
CclUOW constructor . . . . . . . . 95
Public methods . . . . . . . . . . 95
Chapter 4. C and COBOL . . . . . . . 97
External Call Interface . . . . . . . . 97
CICS_ExternalCall ECI_Parms . . . 97
Call types for the CICS_ExternalCall . . 100
ECI status block . . . . . . . . . 128
CICS_EciListSystems NameSpace
Systems List . . . . . . . . . . 129
External Presentation Interface . . . . . 130
EPI constants and data structures . . . 130
EPI functions . . . . . . . . . . 137
EPI events . . . . . . . . . . . 166
External Security Interface . . . . . . . 169
ESI constants and data structures . . . 169
ESI functions . . . . . . . . . . 171
Appendix A. COM Global Constants. . . 181
Appendix B. COM EPI Specific Constants 183
Synchronization Types . . . . . . . . 183
CclEPI States . . . . . . . . . . . 183
iv CICS Transaction Gateway: Programming Reference
|
|
CclSession States . . . . . . . . . . 183
CclTerminal States . . . . . . . . . 183
CclTerminal ATI States . . . . . . . . 184
CclTerminal EndTermReasons. . . . . . 184
CclTerminal Signon Types . . . . . . . 184
CclScreen AID key codes . . . . . . . 185
CclField Protected State Attributes . . . . 186
CclField Numeric Attributes . . . . . . 186
CclField Intensity Attributes . . . . . . 186
CclField Modified Attributes . . . . . . 186
CclField Highlight Attributes . . . . . . 187
CclField Transparency Attributes. . . . . 187
CclField Color Attributes . . . . . . . 187
Appendix C. ECI Constants . . . . . . 189
Synchronization Types . . . . . . . . 189
Flow status types . . . . . . . . . . 189
Connection Status Codes . . . . . . . 189
Appendix D. COM Error Code References 191
Appendix E. Java encodings . . . . . 195
Appendix F. C++ Exception Objects . . . 199
The product library and related literature 205
CICS Transaction Gateway books . . . . 205
Sample configuration documents. . . . . 206
Redbooks . . . . . . . . . . . . 207
Other Useful Books . . . . . . . . . 207
CICS Transaction Server publications . . 207
Microsoft ® Windows Family publications 208
APPC-related publications . . . . . . 208
TCP62–related publications . . . . . 209
Obtaining books from IBM. . . . . . . 209
Accessibility . . . . . . . . . . . 211
Documentation. . . . . . . . . . . 211
Glossary . . . . . . . . . . . . 213
Index . . . . . . . . . . . . . 225
Notices . . . . . . . . . . . . . 251
Trademarks . . . . . . . . . . . . 253
Sending your comments to IBM . . . . 255

About this book
This book provides information about the APIs of the programming languages
that the CICS Transaction Gateway supports (Java , C++, C, and COM). It is
a quick reference for anyone writing Client applications for the Gateway. For
information about programming methodology see the CICS Transaction
Gateway: Programming Guide, SC34-6141.
Who should read this book
This book is intended for anyone involved with programming for CICS
Transaction Gateway.
It is assumed that you are familiar with the operating system under which
your CICS Transaction Gateway runs.
An understanding of Internet terminology is helpful.
Conventions and terminology used in this book
A number of parts, both internal and external to the CICS Transaction
Gateway, are used when creating a business solution using the product.
Figure 1 on page vi shows some of the possible scenarios you will encounter,
and the terminology used in each case.
© Copyright IBM Corp. 1989, 2002 v

Distributed platforms running in remote mode
Java client
application
z/OS running in local mode
Java client
application
Gateway
classes
Gateway
classes
CICS
server
Gateway
daemon
Distributed platforms running in local mode
Java client
application
Gateway
classes
Client
daemon
Distributed platforms running non-Java applications
Client
application
Client
daemon
z/OS running in remote mode
Java client
application
Gateway
classes
CICS
server
Gateway
daemon
Client
daemon
CICS
server
CICS
server
Figure 1. CICS Transaction Gateway uses, with their associated terminology
CICS
server
The following explains the terms used in Figure 1:
Gateway daemon
Used only in remote mode, the Gateway daemon listens on protocols
defined in CTG.INI for gateway requests from remote Java client
applications. It issues these requests to the Client daemon on
distributed platforms, and directly to CICS over the EXCI on z/OS ® .
The Gateway daemon runs the protocol listener threads, the worker
threads and the connection manager threads. It uses the GATEWAY
section of CTG.INI (and on z/OS the ctgenvvar script) for its
configuration.
Client daemon
The Client daemon (process cclclnt) exists only on distributed
platforms. 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.
vi CICS Transaction Gateway: Programming Reference

Gateway classes
The interface for Java Client applications to connect to the Gateway
daemon. The Gateway classes, which are supplied with the CICS
Transaction Gateway, must be in the classpath for Java Client
applications to run.
Client application
A user application, written in a supported programming language
other than Java, that communicates directly with the Client daemon.
Java Client application
A Java application, servlet or applet that communicates with the
Gateway classes.
Installation path
The term is used in file paths to represent the directory where
you installed the product. See the CICS Transaction Gateway: Administration
book for your operating system, for the default installation locations.
Directory delimiters
References to directory path names in this book use the Microsoft ® Windows ®
convention of a backslash (\) as delimiter, instead of the forward slash (/)
delimiter used on z/OS and UNIX ® operating systems.
Programming language specific
The term C refers to both the C and C++ programming languages.
Operating system specific
Unless otherwise specified, the term Windows refers to Windows NT ® ,
Windows 2000, and Windows XP.
The term Windows 2000 Terminal Server means a server with the Terminal
Services feature installed.
Unless otherwise specified, the term z/OS refers to OS/390 ® and z/OS.
About this book vii

viii CICS Transaction Gateway: Programming Reference

|
|
Summary of changes
This book contains material that previously appeared in these books:
v CICS Transaction Gateway Gateway Programming, SC34-5938
v CICS Transaction Gateway C++ Programming, SC34-5945
v CICS Transaction Gateway COM Automation Programming, SC35-5946
v CICS Family Client/Server Programming, SC34-5947
Vertical lines at the left side of the page indicate material that is new to this
edition.
The following functional changes have been made for CICS Transaction
Gateway Version 5.0:
v The Windows XP operating system is supported.
v COBOL is supported on the Windows operating system.
The Java API has the following changes:
v The setCommareaInboundLength() method has been deprecated.
v A new method, getInboundDataLength(), is introduced. The new method
returns the amount of data flowed over the network (with trailing nulls
removed), not the amount of data returned from the CICS transaction.
See the online Java programming reference information for details.
A new state enumeration, CclTerminal::txnTimedOut, has been added for the
C++ libraries.
© Copyright IBM Corp. 1989, 2002 ix

x CICS Transaction Gateway: Programming Reference

Chapter 1. COM
Buffer COM class
A CclOBuffer object contains a data area in memory which can be used to
hold information. A particular use for a CclOBuffer object is to hold a
COMMAREA used to pass data to and from a CICS server.
The CclOBuffer object is primarily intended for use with byte (binary) data.
Typically a COMMAREA contains an application-specific data structure, often
originating from a CICS server C program. The preferred method for handling
binary data in Visual Basic is now the Byte data type. The SetData and Data
methods allow the contents of the CclOBuffer object to be accessed as a Byte
array. The CclOBuffer object can be used for string data, and stores strings as
single-byte ANSI characters, but it does not provide any support for
code-page conversions or DBCS. Note that in 32-bit environments Visual Basic
uses 2-byte Unicode character representation; the COM class converts this to
and from single-byte ANSI.
When a CclOBuffer object is created it allocates an area of memory as its
buffer. The length of this buffer can be set explicitly via the SetLength
method.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOBuf
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
set var = CreateObject("Ccl.Buffer")
set var = New CclOBuf
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
© Copyright IBM Corp. 1989, 2002 1

COM class: Buffer
Methods
AppendString
AppendString(string as String)
string
The source string.
Appends a string to existing data in the Ccl.Buffer object.
Data
Data() as Variant
Returns the contents of the buffer as a Byte array.
ExtractString
ExtractString (offset as Integer[,
length as Integer]) as String
offset
The offset into the data area.
length
(optional) The length, in bytes, of the string to be extracted.
Returns a string from the data area starting at the specified offset.
If length is not specified, ExtractString returns data until it finds the first null
terminator. If length is specified, ExtractString returns the number of bytes
requested, including any nulls found in the string.
InsertString
InsertString (offset as Integer,
string as String)
offset
The offset in the data area where the string is to be inserted.
string
The source string.
Inserts the given string into the data area at the given offset.
2 CICS Transaction Gateway: Programming Reference

Length
Length() as Integer
Returns the length of the data area in bytes.
Overlay
Overlay (offset as Integer,
string as String)
offset
The offset in the data area where the string is to be inserted.
string
The source string.
Overlays the data area with the given string, starting at the given offset.
SetData
SetData(array as Variant)
array
The array containing the source data.
Copies the supplied array into the buffer. Byte, Integer, and Long arrays are
supported.
SetLength
SetLength(length as Integer)
length
The new length of the data area, in bytes.
Changes the current length of the data area. If you increase the length of the
buffer object, the extra space is padded with nulls. The Client daemon
truncates any nulls before sending the buffer to a CICS server.
SetString
SetString(string as String)
COM class: Buffer
Chapter 1. COM 3

COM class: Buffer
string
Source string
Copies the supplied string into the object.
String
Connect COM class
Returns the contents of the Ccl.Buffer object as a string.
The Connect COM class is used to maintain and represent an ECI connection
between a client and a named server. Access to the server is optionally
controlled by a user ID and password. It can call a program in the server or
get information on the state of the connection.
Before the Connect COM class can be used to make calls to CICS, it must be
initialized using the Details method and, optionally, the TranDetails method.
Any interaction between client and server requires a CclOFlow object and a
CclOConnect object.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOConn
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
Methods
String() as String
set var = CreateObject("Ccl.Connect")
set var = New CclOConn
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
AlterSecurity
AlterSecurity(newUserid as String, newPassword as String)
4 CICS Transaction Gateway: Programming Reference

newUserid
The new userid
newPassword
The new password corresponding to the new userid.
Sets the userid and password to be used on the next link call.
Cancel
Cancel(flow as Object)
or
Cancel(flow as CclOFlow)
flow
The CclOFlow object used to control the client/server call
Cancels any Changed call that was previously issued to the server associated
with this connection.
Changed
Changed(flow as Object)
or
Changed(flow as CclOFlow)
flow
The CclOFlow object used to control the client/server call.
Requests the server to notify the client when the current connection status
changes. The call is ignored if there is an outstanding Changed call for this
connection.
ChangePassword
ChangePassword (newPassword as String) as Object
or
ChangePassword (newPassword as String) as CclOSecAttr
COM class: Connect
Chapter 1. COM 5

COM class: Connect
newPassword
The new password
Allows a client application to change the password held in the Connect object
and the password recorded by an external security manager for the userid
held in the Connect object. The external security manager is assumed to be
located in the server defined by the Connect object. A CclOSecAttr object is
returned if no errors occur.
Details
Details (serverName as String,
userId as String,
password as String)
serverName
The name of the server. If no name is supplied the default server—the
first server named in the Gateway initialization file—is used. You can
discover this name, after the first call to the server by using the
ServerName method. The length is adjusted to 8 characters by padding
with blanks.
userId
The user ID, if needed. The length is adjusted to 16 characters by padding
with blanks.
password
The password corresponding to the user ID in userID, if needed. The
length is adjusted to 16 characters by padding with blanks.
Use this method to supply details of the CICS server. No interaction with the
CICS server takes place until the Link, Status or Changed methods are called.
The user ID and password are not needed if the connection is only used for
status calls or if the server has no security.
6 CICS Transaction Gateway: Programming Reference

Link
Link (flow as Object,
programName as String,
commArea as Object,
unitOfWork as Object)
or
Link (flow as CclOFlow,
programName as String,
commArea as CclOBuf,
unitOfWork as CclOUOW)
flow
The CclOFlow object used to control the client/server call.
programName
The name of the server program that is being called. The length is
adjusted to 8 characters by padding with blanks or truncating, if
necessary.
commArea
A CclOBuffer object that holds the data to be passed to the called program
in a COMMAREA. A NULL value should be supplied if no COMMAREA
is to be sent.
unitOfWork
The CclOUOW object that identifies the unit of work (UOW) with which
this call is being associated. A NULL value should be supplied if no UOW
is to be used.
Calls the specified program on the server. The server program sees the
incoming call as an EXEC CICS LINK call.
MakeSecurityDefault
MakeSecurityDefault()
Informs the client that the current userid and password for this object is to
become the default for ECI and EPI requests passed to the server as specified
in the construction of the Connect object.
Password
Password() as String
COM class: Connect
Returns the password held by the CclOConnect object, padded with spaces.
Chapter 1. COM 7

COM class: Connect
ServerName
ServerName() as String
Returns the name of the server system held by the CclOConnect object and
listed by the Gateway initialization file, or blanks if the default server is being
used and no calls have yet been made.
ServerStatus
ServerStatus() as Integer
or
ServerStatus() as CclConnectStatusCodes
Returns the status of the server connection, set by an earlier status or changed
request. Possible values are:
cclUnknown
The CICS server status is unknown
cclAvailable
The CICS server is available
cclUnavailable
The CICS server is not available
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
ServerStatusText
ServerStatusText() as String
Returns a string, set by an earlier status or changed request, indicating the
availability of the server.
Status
Status(flow as Object)
or
Status(flow as CclOFlow)
8 CICS Transaction Gateway: Programming Reference

flow
The CclOFlow object used to control the client/server call
Request the status of the server connection.
TranDetails
TranDetails (runTran as String,
attachTran as String)
runTran
The CICS transaction under which called programs will run. The default
is to use the default server transaction. The length is adjusted to four
characters by padding with blanks.
attachTran
The CICS transaction to which called programs are attached. The default
is to use the default CPMI. The length is adjusted to four characters by
padding with blanks.
This method is used to supply additional information to the CICS server. The
information is optional, but can be used to affect the environment in which
programs are run on the CICS server.
Note: Use the Details method, to supply details of the CICS server, before
using the TranDetails method; see “Details” on page 6.
UnpaddedPassword
UnpaddedPassword() as String
Returns the password held by the CclOConnect object, but with no padding
with spaces at the end.
UnpaddedServerName
UnpaddedServerName() as String
Returns the server name held by the CclOConnect object, but with no
padding with spaces at the end.
UnpaddedUserid
UnpaddedUserid() as String
COM class: Connect
Chapter 1. COM 9

COM class: Connect
Returns the userid held by the CclOConnect object, but with no padding with
spaces at the end.
UserId
UserId() as String
Returns the user ID held by the CclOConnect object, padded with spaces, or
blanks if none.
VerifyPassword
VerifyPassword() as Object
or
VerifyPassword() as CclOSecAttr
Allows a client application to verify that the password held in the Connect
object matches the password recorded by an external security manager for the
userid held in the Connect object. The external security manager is assumed
to be located in the server defined by the Connect object. A CclOSecAttr
Object is returned if no errors occur.
ECI COM class
All applications using the ECI COM class must first create a CclOECI object.
The ECI COM class provides details of candidate CICS servers. It can also be
used to obtain error information.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOECI
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
set var = CreateObject("Ccl.ECI")
set var = New CclOECI
10 CICS Transaction Gateway: Programming Reference

Methods
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
ErrorFormat
ErrorFormat() as Integer
Returns a value indicating the current setting for the Error Message Format.
Refer to SetErrorFormat for a current list of valid values.
ErrorOffset
ErrorOffset() as Long
Returns a value which can be used to convert a Client daemon error value
retrieved from the ERR.Number method into the documented ExCode error
values. For more information on how to do this, refer to CICS Transaction
Gateway: Programming Guide.
ErrorWindow
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ErrorWindow(display as Boolean)
display
true Permits the error window to be displayed to the user. This is the
default setting.
false The error window will not be displayed to the user. The
application must check for errors using the ExCode method.
ExCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ExCode() as Integer
COM class: ECI
Chapter 1. COM 11

COM class: ECI
or
ExCode() as CclECIExceptionCodes
Returns an enumeration that indicates the last ECI error.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
The ExCodeText method returns a text string describing the error value.
ExCodeText
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ExCodeText() as String
Returns a text string describing the last ECI error.
ServerCount
ServerCount() as Integer
Returns the number of candidate servers to which the client may be
connected, as configured in the Gateway initialization file.
ServerDesc
ServerDesc(index as Integer) as String
index
The number of a connected server in the list, starting from 1
Returns the description of the indexth server.
ServerName
ServerName(index as Integer) as String
index
The number of a connected server in the list, starting from 1
12 CICS Transaction Gateway: Programming Reference

Returns the name of the indexth server.
SetErrorFormat
SetErrorFormat(format as Integer)
format
0 Old format, provided for backward compatability only.
1 New format, provides more information in the Visual Basic and
VBScript Err object. This format is recommended.
This method allows you to select an error message format.
EPI COM class
The EPI COM class initializes the Client daemon EPI function. It also has
methods that allow you to obtain information about CICS servers which could
be used. You create a CclOEPI object before you create CclOTerminal objects
to connect to CICS servers. The Diagnose, ExCode, and State methods
provide information on error conditions.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOEPI
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways
Methods
set var = CreateObject("Ccl.EPI")
set var = New CclOEPI
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
Diagnose
Diagnose() as String
Returns a character string which holds a description of the last error.
COM class: ECI
Chapter 1. COM 13

COM class: EPI
ErrorFormat
ErrorFormat() as Integer
Returns a value indicating the current setting for the Error Message Format.
Refer to “SetErrorFormat” on page 16 for a current list of valid values.
ErrorOffset
ErrorOffset() as Long
Returns a value which can be used to convert a Client daemon error value
retrieved from the ERR.Number method into the documented ExCode error
values. For more information on how to do this, refer to CICS Transaction
Gateway: Programming Guide.
ErrorWindow
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ErrorWindow(display as Boolean)
display
true Permits the error window to be displayed to the user. This is the
default setting.
false The error window will not be displayed to the user. The
application must check for errors using the ExCode method.
ExCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ExCode() as Integer
or
ExCode() as CclEPIExceptionCodes
14 CICS Transaction Gateway: Programming Reference

Returns the condition code. Possible values are:
cclSystemError
An internal Client daemon system error occurred.
cclUnknownServer
There is no CICS server corresponding to the supplied index on
ServerDesc or ServerName methods.
cclNoError
The call has executed normally.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
ExCodeText
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ExCodeText() as String
Returns a string containing descriptive text for the most recent exception.
ServerCount
ServerCount() as Integer
Returns the number of candidate servers to which the Client daemon may be
connected, as configured in the Gateway initialization file.
ServerDesc
ServerDesc(index as Integer) as String
index
The index number of a connected server (starting from 1).
COM class: EPI
Returns a description of the selected CICS server, or a NULL string if no
information is available in the Gateway initialization file for the specified
server.
Chapter 1. COM 15

COM class: EPI
ServerName
ServerName(index as Integer) as String
index
The index number of a connected server (starting from 1).
Returns the name of the requested CICS server, or a NULL string if no
information is available in the Gateway initialization file for the specified
server.
SetErrorFormat
SetErrorFormat(format as Integer)
format
0 Old format, provided for backward compatability only.
1 New format, provides more information in the Visual Basic and
VBScript Err object. This format is recommended.
This method allows you to select an error message format.
State
State() as Integer
or
State() as CclEPIStates
Returns a value which indicates the state of the EPI. Possible values are:
cclActive
Initialized
cclDiscon
Terminated
cclError
Error. Refer to CICS Transaction Gateway: Programming Guide.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
16 CICS Transaction Gateway: Programming Reference

Terminate
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
Terminates the Client daemon EPI in a controlled manner.
Field COM class
The Field COM class is used to access a single field on a 3270 screen.
CclOField objects are created and deleted when 3270 data from the CICS
server is processed by a CclOScreen object.
Field objects are returned by invoking a CclOScreen object’s fieldbyIndex or
fieldbyPosition method. For example:
set var=Screen.fieldbyIndex(1)
Methods in this class allow field text and attributes to be read and updated.
Updated fields are sent to the CICS server on the next transmission.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOField
Methods
Terminate()
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
AppendText
AppendText(textString as String)
textString
The text string to be appended to the field.
COM class: EPI
Chapter 1. COM 17

COM class: Field
Appends the characters within textString to the end of the text already in the
field.
BackgroundColor
BackgroundColor() as Integer
or
BackgroundColor() as CclColorAttributes
Returns a value which indicates the background color of the field as listed in
“CclField Color Attributes” on page 187.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
BaseAttribute
BaseAttribute() as Integer
Returns the 3270 base attribute of the field.
Column
Column() as Integer
Returns the column number of the position of the start of the field on the
screen, with the leftmost column being 1.
DataTag
DataTag() as Integer
or
DataTag() as CclModifiedAttributes
Returns a value which indicates whether the data in the field has been
modified. Possible values are:
cclModified
cclUnmodified
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
18 CICS Transaction Gateway: Programming Reference

ForegroundColor
ForegroundColor() as Integer
or
ForegroundColor() as CclColorAttributes
Returns a value which indicates the foreground color of the field as listed in
“CclField Color Attributes” on page 187.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
Highlight
Highlight() as Integer
or
Highlight() as CclHighlightAttributes
Returns a value which indicates which type of highlight is being used as
listed in “CclField Highlight Attributes” on page 187.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
InputProt
InputProt() as Integer
or
InputProt() as CclProtAttributes
COM class: Field
Returns a value which indicates whether the field is protected. Possible values
are:
cclProtect
cclUnprotect
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
Chapter 1. COM 19

COM class: Field
InputType
InputType() as Integer
or
InputType() as CclNumericAttributes
Returns a value which indicates whether the field is alphanumeric or numeric.
Possible values are:
cclAlphanumeric
cclNumeric
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
Intensity
Intensity() as Integer
or
Intensity() as CclIntensityAttributes
Returns a value which indicates whether the field is normal, intense or dark.
Possible values are:
cclDark
cclNormal
cclIntense
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
Length
Length() as Integer
Returns the total length of the field. This includes one byte used to store the
3270 attribute byte information; therefore the actual space for data is one less
byte than the value returned by this method. See also the TextLength method.
Position
Position() as Integer
20 CICS Transaction Gateway: Programming Reference

Returns the position of the start of the field as an offset from the top left
corner of the screen. The top row consists of positions 0 to 79; the second row,
positions 80 to 159; etc.
ResetDataTag
ResetDataTag()
Resets the modified data tag (MDT) to cclUnmodified.
Row
Row() as Integer
Returns the row number of the position of the start of the field on the screen.
The top row is 1.
SetBaseAttribute
SetBaseAttribute(Attribute as Integer)
Attribute
The value of the base 3270 attribute to be entered into the field.
Sets the 3270 base attribute.
SetExtAttribute
SetExtAttribute(Attribute as Integer, Value as Integer)
Attribute
The type of extended attribute to be set.
Value
The value of the extended attribute.
Sets the extended 3270 attribute. If an invalid 3270 attribute type or value is
supplied a parameter exception is raised.
SetText
SetText(textString as String)
COM class: Field
Chapter 1. COM 21

COM class: Field
textString
The null-terminated text to be entered into the field.
Copies textString into the field.
Text
Text() as String
Returns the text currently held in the field.
TextLength
TextLength() as Integer
Returns the number of characters currently held in the field.
Transparency
Transparency() as Integer
or
Transparency() as CclTransparencyAttributes
Returns a value which indicates the background transparency of the field as
listed in “CclField Transparency Attributes” on page 187.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
Flow COM class
A CclOFlow object is used to control ECI communications for a client/server
pair.
A CclOFlow object is created for each client server interaction (call from client
and response from server) and destroyed when it has been used. CclOFlow
objects can be reused but an attempt to reuse a CclOFlow object that is
already in use is rejected.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOFlow
22 CICS Transaction Gateway: Programming Reference

The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
Methods
set var = CreateObject("Ccl.Flow")
set var = New CclOFlow
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
AbendCode
AbendCode() as String
Returns a four-character CICS transaction abend code, or spaces if no abend
has occurred.
CallType
CallType() as Integer
or
CallType() as CclFlowCallTypes
Returns the type of call the flow is currently executing.current
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
CallTypeText
CallTypeText() as String
Returns the type of call the flow is currently executing as text.
Diagnose
Diagnose() as String
Returns text describing the current state of the flow object.
COM class: Flow
Chapter 1. COM 23

COM class: Flow
Flowid
Flowid() as Integer
Returns a unique identifier for this flow object.
ForceReset
ForceReset()
Makes the flow inactive and resets it. Typically, this method is used to prepare
a flow object for re-use or deletion after a flow has been abandoned.
Poll
Poll(commArea as Object) as Boolean
or
Poll(commArea as CclOBuf) as Boolean
commArea
A CclOBuffer object into which the returned COMMAREA will be placed.
This parameter can be set to Nothing if no COMMAREA should be
returned.
Indicates whether a reply has been received from a deferred synchronous
Backout, Cancel, Changed, Commit, Link, orStatus call request. This method
is only valid for deferred synchronous communications. Possible values are:
True A reply has been received.
False A reply has not been received.
SetSyncType
SetSyncType(syncType as Integer)
or
SetSyncType(syncType as CclFlowSyncTypes)
syncType
The synchronization type required for this CclOFlow object. Possible
values are:
cclSync
cclDSync
Sets the synchronization type required for this CclOFlow object. If cclSync is
used, link and status calls using this flow block the calling program until a
reply is received from CICS. If cclDSync is used, link and status calls using
24 CICS Transaction Gateway: Programming Reference

this flow return immediately to the calling program. The program can then
use the Poll method to receive the reply from CICS later.
SetTimeout
SetTimeout(Timeout as Integer)
Sets the timeout value for the flow object for the next activation of the flow.
This value can be set while a flow is active, but does not affect the current
active flow.
SyncType
SyncType() as Integer
or
SyncType() as CclFlowSyncTypes
Returns the type of synchronisation being used.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
Timeout
Timeout() as Integer
Returns the current timeout value set for the flow object.
Wait
Wait()
COM class: Flow
Waits for a reply from the server, blocking the client process in the meantime.
This method is used when a deferred synchronous call was made, but the
application now wants to wait synchronously for a reply.
Chapter 1. COM 25

|
|
|
|
COM class: Map
Map COM class
The Map COM class provides validation and access to 3270 screen data using
symbolic information obtained from CICS BMS maps. To use this interface,
run the CICSBMSC utility on your server program BMS maps.
Linux
Note: CICSBMSC is not provided with CICS Transaction Gateway for the
Linux operating system. If you require this functionality, contact your
local IBM ® support representative and ask them to forward your
request to the CICS service team.
End of Linux
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOMap
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
Methods
set var = CreateObject("Ccl.Map")
set var = New CclOMap
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
ExCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ExCode() as Integer
or
26 CICS Transaction Gateway: Programming Reference

ExCode() as CclEPIExceptionCodes
Returns a value that indicates the current condition code.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
FieldByName
FieldByName(name as Integer) as Object
or
FieldByName(name as Integer) as CclOField
name
Symbolic value for the required field. This value is provided in the
.BAS file generated from the source BMS by the CICSBMSC
utility.
Returns the specified CclOField object.
Validate
Validate (screenRef as Object, mapname as String) as Boolean
or
Validate (screenRef as CclOScreen, mapname as String) as Boolean
screenRef
CclOScreen object
mapname
String value supplied in .BAS file generated from the source
BMS by the CICSBMSC utility.
Validate map against the current screen.
COM class: Map
This method can be used to verify that a specific BMS map has been received
from the CICS server. Possible return values are:
TRUE
Specified BMS map matches current screen contents.
FALSE
Specified BMS map does not match current screen contents
If TRUE is returned, the FieldByName method can be used to access fields
using their BMS name.
Chapter 1. COM 27

COM class: Screen
Screen COM class
The Screen COM class maintains all data on the 3270 virtual screen and
provides access to this data. It contains a collection of CclOField objects which
represent the fields on the current 3270 screen.
A single Screen object is created by the Terminal object when the terminal is
installed either with the Ccl Terminal connect or install method. The
application gets access to the CclOScreen object via the Ccl Terminal Screen
method.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOScreen
Methods
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
CursorCol
CursorCol() as Integer
Returns the current cursor column (the left col is 1).
CursorRow
CursorRow() as Integer
Returns the current cursor row (the top row is 1).
Depth
Depth() as Integer
Returns the number of rows on the screen.
28 CICS Transaction Gateway: Programming Reference

FieldByIndex
FieldByIndex(index as Integer) as Object
or
FieldByIndex(index as Integer) as CclOField
index
The index number of the field required. The first field is number 1.
FieldByPosition
FieldByPosition (rowPos as Integer, colPos as Integer) as Object
or
FieldByPosition (rowPos as Integer, colPos as Integer) as CclOField
rowPos
The row number of the field (topmost row = 1).
colPos
The column number of the field (leftmost column = 1).
FieldCount
FieldCount() as Integer
Returns the number of fields on the screen.
MapName
MapName() as String
Returns a string specifying the name of the map that was most recently
referenced in the MAP option of a SEND MAP command processed for the
terminal resource. If the terminal resource is not supported by BMS, or the
server has no record of any map being sent, the value returned is blank.
MapSetName
MapSetName() as String
COM class: Screen
Returns a string specifying the name of the mapset that was most recently
referenced in the MAPSET option of a SEND MAP command processed for
the terminal resource. If the MAPSET option was not specified on the most
recent request, BMS used the map name as the mapset name. In both cases,
the mapset name used may have been suffixed by a terminal suffix. If the
Chapter 1. COM 29

COM class: Screen
terminal resource is not supported by BMS, or the server has no record of any
mapset being sent, the value returned is blank.
SetAID
SetAID(key as Integer)
or
SetAID(key as CclADIKeys)
key
The AID key value as listed in “CclScreen AID key codes” on page 185.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
Sets the AID key value to be passed to the server on the next transmission.
SetCursor
rowPos
The required row number of the cursor (the top row is 1).
colPos
The required column number of the cursor (the left column is 1).
Width
SecAttr COM class
SetCursor (rowPos as Integer, colPos as Integer)
Width() as Integer
Returns the number of columns on the screen.
The SecAttr COM class provides information about passwords reported back
by the external security manager when issuing verifySecurity or
changePassword methods on CclOConnect or CclOTerminal objects.
This object is created and owned by the CclOConnect or CclOTerminal Object
and access to this object is provided when invoking the VerifyPassword or
ChangePassword methods.
Interface Selection
For Visual Basic, the following types of interface are available:
30 CICS Transaction Gateway: Programming Reference

Methods
Dim var as Object
Dim var as CclOSecAttr
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
ExpiryTime
ExpiryTime() as Object
or
ExpiryTime() as CclOSecTime
Returns a CclOSecTime object that contains the date and time when the
password will expire.
InvalidCount
InvalidCount() as Integer
Returns the number of times an invalid password has been entered for the
userid.
LastAccessTime
LastAccessTime() as Object
or
LastAccessTime() as CclOSecTime
Returns a CclOSecTime object which contains the date and time when the
userid was last accessed.
LastVerifiedTime
LastVerifiedTime() as Object
or
LastVerifiedTime() as CclOSecTime
COM class: Screen
Chapter 1. COM 31

COM class: Screen
Returns a CclOSecTime object which contains the date and time of the last
verification.
SecTime COM class
The SecTime COM class provides date and time information in the
CclOSecAttr object for various entries reported back by the external security
manager when issuing verifySecurity or changePassword methods on Connect
or Terminal objects.
These objects are created and owned by the CclOSecAttr object and access is
obtained via the various methods available on this object. No constructors or
destructors are available.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOSecTime
Methods
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Day
unsigned short Day() as Integer
Returns the day in the range 1 to 31.
GetDate
GetDate() as Date
Returns the date and time in a Visual Basic DATE type format.
Hours
unsigned short Hours() as Integer
Returns the hours in the range 0 to 23.
32 CICS Transaction Gateway: Programming Reference

Hundredths
unsigned short Hundredths() as Integer
Returns the hundredths of a second in the range 0 to 99.
Minutes
unsigned short Minutes() as Integer
Returns the minutes in the range 0 to 59.
Month
unsigned short Month() as Integer
Returns the month in the range 1 to 12.
Seconds
unsigned short Seconds() as Integer
Returns the seconds in the range 0 to 59.
Year
Session COM class
unsigned short Year() as Integer
Returns a 4 digit year.
The Session COM class controls the flow of data to and from CICS within a
single EPI session.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOSession
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
COM class: Screen
Chapter 1. COM 33

COM class: Session
Methods
set var = CreateObject("Ccl.Session")
set var = New CclOSession
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
Diagnose
Diagnose() as String
Returns the text description of the current state of the session.
SetSyncType
SetSyncType(syncType as Integer)
or
SetSyncType(syncType as CclFlowSyncTypes)
syncType
The synchronization type required for this CclOSession object. Possible
values are:
cclSync
cclDSync
Sets the synchronization type required for this CclOSession object. If cclSync is
used, Start and Send calls using this flow will block the calling program until
a reply is received from CICS. If cclDSync is used, Start and Send calls using
this flow will return immediately to the calling program. The program can
then use the Poll method to receive the reply from CICS at a later time.
State
State() as Integer
or
State() as CclEPIStates
Returns a value which indicates the current state of the session. Possible
values are:
cclActive
Connected
34 CICS Transaction Gateway: Programming Reference

cclServer
Transaction in progress in the CICS server.
cclClient
CICS server is waiting for a response from the client
cclDiscon
Disconnected
cclError
Error, call ExCode and Diagnose methods for further information.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
TransId
TransId() as String
Returns the four-letter name of the current transaction.
Terminal COM class
The Terminal COM class represents a 3270 terminal connection to a CICS
server. A CICS connection is established when the Connect method is called.
Methods can then be used to converse with a 3270 terminal application (often
a BMS application) in the CICS server.
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOTerminal
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
set var = CreateObject("Ccl.Terminal")
set var = New CclOTerminal
COM class: Session
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
Chapter 1. COM 35

COM class: Terminal
Methods
AlterSecurity
AlterSecurity(newUserid as String,newPassword as String)
newPassword
The new password to be given to newUserid.
newUserid
The new userid.
Allows you to redefine the userid and password for a terminal resource that
has been constructed without them (a signon incapable terminal). The method
can be called before you install a terminal. It changes the terminal definition;
the new userid and password are be used for the terminal when install is
called.
CCSId
CCSId() as long
Returns a long showing the selected code page.
ChangePassword
ChangePassword(newPassword as String) as Object
or
ChangePassword(newPassword as String) as CclOSecAttr
newPassword
The new password to be given
Allows a client application to change the password held in the terminal object
and the password recorded by an external security manager for the userid
held in the terminal object. The external security manager is assumed to be
located in the server defined by the terminal object. A CclOSecAttr Object is
returned if no errors occurred.
Connect
Connect(servName as String,
devType as String,
nworkName as String)
36 CICS Transaction Gateway: Programming Reference

servName
The name of the server with which you want to communicate. If a NULL
string is provided, the default server system, defined in the Gateway
initialization file, is assumed. The name is expanded to 8 characters by
padding with blanks, if necessary.
devType
The name of the model terminal definition which the server uses to
generate a terminal resource definition. If a NULL string is provided the
default model is used. The name is expanded to 16 characters by padding
with blanks, if necessary.
nworkName
The name of the terminal resource to be installed or reserved. The name is
expanded to 8 characters by padding with blanks, if necessary. If a NULL
string is supplied, the CICS server allocates a name.
Establishes a 3270 communication to the specified CICS server.
Devtype
Devtype() as String
Returns the terminal device type as a string.
Diagnose
Diagnose() as String
Returns a character string which holds a description of the error returned by
the most recent server call.
Disconnect
Disconnect()
Disconnects the terminal from CICS. No attempt is made to purge any
outstanding running transaction.
DisconnectWithPurge
DisconnectWithPurge()
COM class: Terminal
Disconnects the terminal from CICS and attempts to purge any outstanding
running transaction. This purge function does not cancel ATI requests queued
against the terminal.
Chapter 1. COM 37

COM class: Terminal
DiscReason
DiscReason() as CclEndTermReasons
This method will return an enumeration showing the reason the terminal has
been disconnected. Possible values are shown in “CclTerminal
EndTermReasons” on page 184.
ExCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ExCode() as Integer
or
ExCode() as CclEPIExceptionCodes
Returns a value which indicates the most recent condition code returned by
the server.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
ExCodeText
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
ExCodeText() as String
Returns a text string describing the most recent condition code returned by
the server.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
38 CICS Transaction Gateway: Programming Reference

Install
Install(session as Object, timeout as Integer)
or
Install(session as CclOSession, timeout as Integer)
session
The session object to be used by this terminal object.
InstallTimeout
A value in the range 0 through 3600, specifying the maximum time in
seconds that installation of the terminal resource is allowed to take. A
value of 0 means that no limit is set.
This method installs a non-connected terminal resource. A cclInvalidState
error is raised if the terminal is already installed.
MakeSecurityDefault
MakeSecurityDefault()
Informs the client that the current userid and password for this object is to
become the default for ECI and EPI requests passed to the server as specified
in the construction of the Terminal object.
NetName
NetName() as String
Returns the network name of the terminal.
Password
Password() as String
Returns a text string containing the current password for the userid associated
with the terminal. The string is empty if there is no password.
Poll
Poll() as Boolean
COM class: Terminal
Checks to see if a replies have been received from a deferred synchronous
Start or Send request. Possible values are:
True No further replies outstanding
Chapter 1. COM 39

COM class: Terminal
False Further replies outstanding
A CICS server transaction may send more than one reply in response to a
Terminal.Start or Terminal.Send call. More than one Terminal.Poll call may
therefore be needed to collect all the replies. The return code indicates
whether you need to perform more poll requests.
PollForReply
PollForReply() as Boolean
Checks to see if replies have been received from a deferred synchronous Start
or Send request. Possible values are
true Replies have been received
false No replies have been received
A CICS server transaction may send more than one reply in response to a
Terminal.Start or Terminal.Send call. More than one Terminal.PollForReply call
may therefore be needed to collect all replies. Use the Terminal.State method
to find out if further replies are expected. If there are, the value returned will
be cclServer.
QueryATI
QueryATI() as Integer
or
QueryATI() as CclATIStates
Returns a value that indicates whether Automatic Transaction Initiation (ATI)
is enabled or disabled. Possible values are:
cclATIEnabled
cclATIDisabled
ReadTimeout
ReadTimeout() as Integer
Returns the read timeout setting for the terminal.
ReceiveATI
ReceiveATI (session as Object)
or
40 CICS Transaction Gateway: Programming Reference

ReceiveATI (session as CclOSession)
session
A pointer to the CclOSession object which is to be used for the CICS
server interaction.
Waits for and receives 3270 datastream for a CICS ATI transaction. The
CclOSession object supplied can only be synchronous.
Screen
Screen() as Object
Returns the CclOScreen object that is handling the 3270 screen associated with
this terminal.
Send
Send(session as Object)
or
Send(session as CclOSession)
session
The CclOSession object which controls the session which is to be used. It
is set to NULL if no CclOSession object is used.
Generates a 3270 data stream from the current contents of the CclOScreen
object and transmits it to the CICS server.
ServerName
ServerName() as String
Returns the name of the server system held by the CclOTerminal object and
listed by the Gateway initialization file, or blanks if the default server is being
used and no calls have yet been made.
SetATI
SetATI(stateVal as Integer)
or
SetATI(stateVal as CclATIStates)
COM class: Terminal
Chapter 1. COM 41

COM class: Terminal
stateVal
A value which indicates whether the ATI is to be enabled or disabled.
Possible values are:
cclATIEnabled
cclATIDisabled
SetTermDefns
SetTermDefns (servName as String,
devType as String,
nworkName as String
signonCapability as CclSignonTypes
userid as String
password as String
ReadTimeout as Integer
CCSid as Long)
servName
The name of the server with which you want to communicate. If a
NULL string is provided, the default server system, defined in the
Gateway initialization file, is assumed. The name is expanded to 8
characters by padding with blanks, if necessary.
devType
The name of the model terminal definition which the server uses to
generate a terminal resource definition. If a NULL string is provided
the default model is used. The name is expanded to 16 characters by
padding with blanks, if necessary.
nworkName
The name of the terminal resource to be installed or reserved. The
name is expanded to 8 characters by padding with blanks, if
necessary. If a NULL string is supplied, the CICS server will allocate a
name.
signonCapability
Set the signon capability to one of the following:
cclSignonCapable
cclSignonIncapable
ReadTimeout
A value in the range 0 through 3600, specifying the maximum time in
seconds between the time the classes go clientrepl state and the time
that the application program invokes the reply method.
userid The name of the userid to associate with this terminal resource.
password
The password to associate with the userid.
42 CICS Transaction Gateway: Programming Reference

CCSid A long specifying the coded character set indentifier (CCSID) that
identifies the coded graphic character set used by the client
application for data passed between the terminal resource and CICS
transactions. A zero indicates that a default will be used.
Creates a terminal resource but does not make the connection to the Server.
SignonCapability
SignonCapability() as Integer
or
SignonCapability() as CclSignonTypes
Returns the type of terminal installed. Possible values are:
v cclSignonCapable
v cclSignonIncapable
Start
Start (session as Object,
tranCode as String,
startData as String)
or
COM class: Terminal
Start (session as CclOSession,
tranCode as String,
startData as String)
session
The CclOSession object which controls the session which is to be used. It
is set to NULL if no CclOSession object is used.
tranCode
The name of the transaction which is to be started
startData
Start transaction data. A NULL value indicates no data is required for the
transaction being started.
Generates a 3270 data stream from the supplied data and transmits it to the
CICS server, starting the named transaction.
Chapter 1. COM 43

COM class: Terminal
State
State() as Integer
or
State() as CclEPIStates
Returns a value which indicates the current state of the session. These values
are the same as those returned by the state method in the Session COM class.
Constants are available in the type library. Use the Visual Basic Object
Browser to view them.
TermId
TermId() as String
Returns the terminal ID.
TransId
TransId() as String
Returns the 4-character name of the current CICS transaction. Note that if a
RETURN IMMEDIATE is run from the current transaction, TransId does not
provide the name of the new transaction; it still contains the name of the first
transaction.
Userid
Userid() as String
Returns a text string containing the current userid for the terminal. The string
is empty if there is no userid.
VerifyPassword
VerifyPassword() as Object
or
VerifyPassword() as CclOSecAttr
Allows a client application to verify that the password held in the terminal
object matches the password recorded by an external security manager for the
userid held in the terminal object. The external security manager is assumed
44 CICS Transaction Gateway: Programming Reference

to be located in the server defined by the terminal object. A CclOSecAttr
Object is returned if no errors occurred.
UOW COM class
Use this COM class when you make updates to recoverable resources in the
server within a “unit of work” (UOW). Each update in a UOW is identified
by a reference to its CclOUOW object — see Link method in Connect COM
class (“Link” on page 7).
Interface Selection
For Visual Basic, the following types of interface are available:
Dim var as Object
Dim var as CclOUOW
The second method is preferred.
If you do not dim a variable, dim it with no type, or are using VBScript, the
variable is assumed to be of type Object.
Object Creation
You can create an object in two ways:
Methods
set var = CreateObject("Ccl.UOW")
set var = New CclOUOW
New is the preferred method in Visual Basic. For VBScript, you can use only
the CreateObject method.
BackOut
BackOut(flow as Object)
or
COM class: Terminal
BackOut(flow as CclOFlow)
flow
The CclOFlow object which is used to control the client/server call
Terminate this UOW and back out all changes made to recoverable resources
in the server.
Chapter 1. COM 45

COM class: UOW
Commit
Commit(flow as Object)
or
Commit(flow as CclOFlow)
flow
The CclOFlow object which is used to control the client/server call
Terminate this UOW and commit all changes made to recoverable resources in
the server.
ForceReset
ForceReset()
Makes this UOW inactive and resets it. The UOW is neither commited or
backed out.
UowId
UowId() as long
Returns the identifier of the UOW. A zero return indicates that the UOW is
either complete or has not yet started, in other words it is inactive.
46 CICS Transaction Gateway: Programming Reference

Chapter 2. Java
Online programming reference information is provided for the Java classes
and interfaces provided with CICS Transaction Gateway.
The reference information is in HTML format and is generated using the
Javadoc tool provided with the JDK .
To get to the reference information:
v On Windows, select the Programming Reference icon.
v On AIX ® , Solaris, Linux, and HP-UX, run the ctgdoc script.
This displays the library home page, from where you can follow the links
to the reference information.
The following sections describe the different kinds of HTML pages that are
provided within the reference information.
See the README file for the latest information on using the programming
reference information.
Class/interface page
In the reference pages, each class and interface has its own page. In each of
these pages, there are three sections:
1. Class/interface description:
v Class inheritance diagram
v Direct Subclasses
v All Known Subinterfaces
v All Known Implementing Classes
v Class/interface declaration
v Class/interface description
2. Summary tables:
v Inner Class Summary
v Field Summary
v Constructor Summary
v Method Summary
3. Class/interface description:
v Field Detail
© Copyright IBM Corp. 1989, 2002 47

Use page
v Constructor Detail
v Method Detail
Each summary entry contains the first sentence from the detailed description
for that item. The summary entries are alphabetical, while the detailed
descriptions are in the order they appear in the source code. This preserves
the logical groupings established by the programmer.
Each documented class and interface has its own Use page. This page
describes what packages, classes, methods, constructors and fields use any
part of the given class. The Use page for a package or interface A includes:
v Subclasses of A
v Fields declared as A
v Methods that return A
v Methods and constructors with parameters of type A.
To access this page, go to the class or interface, then click on the Use link in
the navigation bar.
Tree (Class Hierarchy)
When viewing a particular class or interface page, selecting Tree displays the
class and interface hierarchy for CICS Transaction Gateway.
Deprecated API
The Deprecated API page lists all of the API that have been deprecated. A
deprecated API is not recommended for use, generally due to improvements.
Deprecated APIs may be removed in future implementations.
Index page
The Index contains an alphabetic list of all classes, interfaces, constructors,
methods, and fields.
48 CICS Transaction Gateway: Programming Reference

Chapter 3. C++
Ccl class
This class defines enumerations which are used by other classes—both ECI
and EPI.
Enumerations
Bool
There are two equivalent pairs of values:
no and yes
off and on
Sync
Possible values are:
async asynchronous
dsync deferred synchronous
sync synchronous
ExCode
For possible values, refer to Table 20 on page 199.
CclBuf class
A CclBuf object contains a data area in memory that can be used to hold
information. A particular use for a CclBuf object is to hold a COMMAREA,
which passes data to and from a CICS server.
The CclBuf object is primarily intended for use with byte (binary) data. A
typical COMMAREA contains an application-specific data structure, often
originating from a CICS server PL/1 or C program. Methods such as assign()
and insert() therefore provide a void* parameter type for application data
input. There is limited support for SBCS null-terminated strings (some of the
code samples make use of this), but there is no code-page conversion or DBCS
support in the CclBuf class.
The maximum data length for a buffer is the maximum value for unsigned
long (2 32 ) for 32 bit platforms. CICS imposes a limit of 32500 bytes in
COMMAREAs. This may be reduced by setting the MaxBufferSize parameter
in the CICS Transaction Gateway initialization file. See the CICS Transaction
© Copyright IBM Corp. 1989, 2002 49

CclBuf Class
Gateway: Administration book for your operating system, for more information.
If a buffer object used as a COMMAREA is too long, a data length exception
is raised.
When a CclBuf object is created it either uses an area of memory passed to it
as its buffer, or allocates its own. The length of the data in this buffer can be
reduced after the CclBuf object is created. The length of the data in this buffer
can only be increased beyond the original length if the CclBuf object is created
with a DataAreaType of extensible, rather than fixed.
If a buffer object has a DataAreaType of fixed and a method is called which
would result in its data area length being exceeded, a buffer overflow
exception is raised. If the exception is not handled, the buffer will contain the
result of the call, truncated to the data area length.
If a method is called that results in a buffer object having a data length
smaller than its data area length, the data is padded with nulls.
Many of the methods return object references. This makes it possible for users
to chain calls to member functions. For example, the code:
CclBuf comma1;
comma1="Some text";
comma1.insert( 9,"inserted ",5) += " at the end";
would create the following string:
Some inserted text at the end
CclBuf constructors
CclBuf (1)
CclBuf(unsigned long length, DataAreaType type = extensible)
length
The initial length of the data area, in bytes. The default is 0.
type
An enumeration indicating whether the data area can be extended.
Possible values are extensible or fixed. The default is extensible.
Creates a CclBuf object, allocating its own data area with the given length. All
the bytes within it are set to null. The data length is set to zero and remains
zero until data is put in the buffer.
CclBuf (2)
CclBuf(unsigned long length, void* dataArea)
50 CICS Transaction Gateway: Programming Reference

length
The length of the supplied data area, in bytes.
dataArea
The address of the first byte of the supplied data area.
Creates a CclBuf object that cannot be extended, adopting the given data area
as its own. The DataAreaOwner is set external.
CclBuf (3)
CclBuf(const char* text, DataAreaType type = extensible)
text
A string to be copied into the new CclBuf object.
type
An enumeration indicating whether the data area can be extended.
Possible values are extensible or fixed. The default is extensible.
Creates a CclBuf object, allocating its own data area with the same length as
the text string and copies the string into its data area.
CclBuf (4)
CclBuf(const CclBuf& buffer)
buffer
A reference to the CclBuf object that is to be copied.
This copy constructor creates a new CclBuf object, which is a copy of the
given object. The data length, data area length and data area type of the new
buffer are the same as the old buffer. The data area owner of the new buffer is
internal.
Public methods
assign
CclBuf& assign(unsigned long length, const void* dataArea)
length
The length of the source data area, in bytes.
dataArea
The address of the source data area.
Overwrites the current contents of the data area with the source data and
resets the data length.
cut
CclBuf& cut(unsigned long length, unsigned long offset =0)
CclBuf Class
Chapter 3. C++ 51

CclBuf Class
length
The number of bytes to be cut from the data area.
offset
The offset into the data area. The default is zero.
Cuts the specified data from the data area. Data in the data area is padded
with nulls.
dataArea
const void* dataArea(unsigned long offset = 0) const
offset
The offset into the data area. The default is zero.
Returns the address of the given offset into the data area.
dataAreaLength
unsigned long dataAreaLength() const
Returns the length of the data area in bytes.
dataAreaOwner
DataAreaOwner dataAreaOwner() const
Returns an enumeration value indicating whether the data area has been
allocated by the CclBuf constructor or has been supplied from elsewhere.
Possible values are internal and external.
dataAreaType
DataAreaType dataAreaType() const
Returns an enumeration value indicating whether the data area can be
extended. Possible values are extensible and fixed.
dataLength
unsigned long dataLength() const
Returns the length of data in the data area. This cannot be greater than the
value returned by dataAreaLength.
52 CICS Transaction Gateway: Programming Reference

insert
CclBuf& insert(unsigned long length,
const void* dataArea,
unsigned long offset =0)
length
The length of the data, in bytes, to be inserted into the CclBuf object.
dataArea
The start of the source data to be inserted into the CclBuf object.
offset
The offset into the data area where the data is to be inserted. The default
is zero.
Inserts the source data into the data area at the given offset.
listState
const char* listState() const
Returns a formatted string containing the current state of the object. For
example:
Buffer state..&CclBuf=000489B4 &CclBufI=00203A00
dataLength=8 &dataArea=002039C0
dataAreaLength=8 dataAreaOwner=0 dataAreaType=1
operator= (1)
CclBuf& operator=(const CclBuf& buffer)
buffer
A reference to a CclBuf object.
Assigns data from another buffer object.
operator= (2)
CclBuf& operator=(const char* text)
text
The string to be assigned to the CclBuf object.
Assigns data from a string.
operator+= (1)
CclBuf& operator+=(const CclBuf& buffer)
buffer
A reference to a CclBuf object.
CclBuf Class
Chapter 3. C++ 53

CclBuf Class
Appends data from another buffer object to the data in the data area.
operator+= (2)
CclBuf& operator+=(const char* text)
text
The string to be appended to the CclBuf object.
Appends a string to the data in the data area.
operator==
Ccl::Bool operator==(const CclBuf& buffer) const
buffer
A reference to a CclBuf object.
Returns an enumeration indicating whether the data contained in the buffers
of the two CclBuf objects is the same. Possible values are yes, indicating that
the data lengths and contents are the same, or no.
operator!=
Ccl::Bool operator!=(const CclBuf& buffer) const
buffer
A reference to a CclBuf object.
Returns an enumeration indicating whether the data contained in the buffers
of the two CclBuf objects is different. Possible values are yes or no. no means
that the data lengths are the same and the contents are the same.
replace
CclBuf& replace(unsigned long length,
const void* dataArea,
unsigned long offset =0)
length
The length of the source data area, in bytes.
dataArea
The address of the start of the source data area.
offset
The position where the new data is to be written, relative to the start of
the CclBuf data area. The default is zero.
Overwrites the current contents of the data area at the given offset with the
source data. The data length remains the same.
54 CICS Transaction Gateway: Programming Reference

setDataLength
unsigned long setDataLength(unsigned long length)
length
The new length of the data area, in bytes.
Changes the current length of the data area and returns the new length. If the
CclBuf object is not extensible, the data area length is set to either the original
length of the data area, or length, whichever is less.
Enumerations
If length is greater than the data area length, the data is padded with nulls.
DataAreaOwner
Indicates whether the data area of a CclBuf object has been allocated outside
the object. Possible values are:
internal
The data area has been allocated by the CclBuf constructor.
external
The data area has been allocated externally.
DataAreaType
CclBuf Class
Indicates whether the data area of a CclBuf object can be made longer than its
original length. Possible values are:
extensible
The data area of a CclBuf object can be made longer than its original
length.
fixed The data area of a CclBuf object cannot be made longer than its
original length.
CclConn class
An object of class CclConn is used to represent an ECI connection between a
client and a named server. See Server connection in the CICS Transaction
Gateway: Programming Guide. Access to the server is optionally controlled by a
userId and password. It can call a program in the server or get information on
the state of the connection. See Passing data to a server program in the CICS
Transaction Gateway: Programming Guide and Monitoring server availability in the
CICS Transaction Gateway: Programming Guide for more information.
The creation of a CclConn object does not cause any interaction with the CICS
server, nor does it guarantee that the server is available to process requests.
Chapter 3. C++ 55

C++ Class: CclConn
Any interaction between client and server requires the use of a CclFlow
object. See Compiling and Linking in the CICS Transaction Gateway: Programming
Guide for more information.
A CclConn object cannot be copied or assigned. Any attempt to delete a
CclConn object for which there are active CclFlow or CclUOW objects raises
an activeFlow or an activeUOW exception.
CclConn constructor
CclConn(const char* serverName =0,
const char* userId =0,
const char* password =0,
const char* runTran =0,
const char* attachTran =0)
serverName
The name of the server. If no name is supplied the default server is used.
After the first call to the server you can discover this name by using the
serverName method. The length is adjusted to 8 characters by padding
with blanks or truncating, if necessary.
userId
The userId, if needed. The length is adjusted to 16 characters by padding
with blanks or truncating, if necessary.
password
The password corresponding to the userId in userID, if needed. The length
is adjusted to 16 characters by padding with blanks or truncating, if
necessary.
runTran
The CICS transaction under which the called program will run. The
default is to use the default server transaction. The length is adjusted to 4
characters by padding with blanks or truncating, if necessary.
attachTran
The CICS transaction to which the called program is attached. The default
is to use the default CPMI. The length is adjusted to 4 characters by
padding with blanks or truncating, if necessary.
This constructor creates a CclConn object; it does not cause any interaction
with the CICS server or guarantee that the server is available to process
requests. The userId and password are not needed if the connection is used
only for status calls, or if the server has no security.
Public methods
alterSecurity
void alterSecurity(const char* newUserid, const char* newPassword)
56 CICS Transaction Gateway: Programming Reference

newUserid
The new userid
newPassword
The new password corresponding to the new userid
Updates the Userid and Password to be used on the next link call
cancel
void cancel(CclFlow& flow)
flow
A reference to the CclFlow object used to control the server request call.
Cancels any changed call that was previously issued to the server associated
with this connection.
changed
void changed(CclFlow& flow)
flow
A reference to the CclFlow object used to control the server request call.
Requests the server to notify the Client daemon when the current connection
status changes. The call is ignored if there is already an outstanding changed
call for this connection. Use serverStatus or serverStatusText to obtain server
availability.
changePassword
CclSecAttr* changePassword(const char* newPassword)
newPassword
the new password to be given
Allows a Client application to change:
v The password held in the terminal object
v The password recorded by an external security manager for the userid held
in the terminal object
The external security manager is assumed to be located in the server defined
by the terminal object.
link
void link(CclFlow& flow,
const char* programName,
CclBuf* commarea =0,
CclUOW* unit =0)
C++ Class: CclConn
Chapter 3. C++ 57

C++ Class: CclConn
flow
A reference to the CclFlow object used to control the server request call.
programName
The name of the server program that is being called. The length is
adjusted to 8 characters by padding with blanks or truncating, if
necessary.
commarea
A pointer to a CclBuf object that holds the data to be passed to the called
program in a COMMAREA. The default is not to pass a COMMAREA.
unit
A pointer to the CclUOW object that identifies the unit of work (UOW) in
which this call participates. The default is none. See Managing logical units
of work in the CICS Transaction Gateway: Programming Guide.
Requests execution of the specified program on the server. The server
program sees the incoming call as an EXEC CICS LINK call.
If the commarea buffer object is too long, a dataLength exception is raised and
the request is denied. CICS imposes a limit of 32500 bytes which can be made
smaller by using the MaxBufferSize parameter in the CICS Transaction
Gateway Initialization file.
listState
const char* listState() const
Returns a formatted string containing the current state of the object. For
example:
Connection state..&CclConn=000489AC &CclConnI=00203A50
flowCount=0 &CclFlow(changed)=00000000 token(changed)=0
serverName="server " userId="userId " password="password "
&CclUOWI=00000000 runTran="run " attachTran="att "
makeSecurityDefault
void makeSecurityDefault()
Informs the client that the current userid and password for this object is to
become the default for ECI and EPI requests passed to the server as specified
in the construction of the connection object.
password (1)
const char* password() const
Returns the password held by the CclConn object, padded with spaces to 10
characters, or blanks if there is no password.
58 CICS Transaction Gateway: Programming Reference

password (2)
void password(Ccl::Bool unpadded)
unpadded
Ccl::Yes
returns a null terminated string of the stored password with no
space padding in the string.
Ccl::No
returns the string padded with spaces — the same as invoking the
password method with no parameters.
serverName (1)
const char* serverName() const
Returns the name of the server system held by the CclConn object, padded
with spaces, or blanks if the default server is being used and no calls have yet
been made.
serverName (2)
void serverName(Ccl::Bool unpadded)
unpadded
Ccl::Yes
returns a null terminated string of the stored server name with no
space padding in the string.
Ccl::No
returns the string padded with spaces — the same as invoking the
serverName method with no parameters.
status
void status(CclFlow& flow)
flow
A reference to the CclFlow object used to control the server request call.
Requests the status of the server connection. When the reply has been
received, use serverStatus or serverStatusText to obtain server availability.
serverStatus
ServerStatus serverStatus() const
C++ Class: CclConn
Chapter 3. C++ 59

C++ Class: CclConn
Returns an enumeration value, set by an earlier status or changed request,
indicating the availability of the server. Possible values are listed under
Enumerations.
serverStatusText
const char* serverStatusText() const
Returns a string, set by an earlier status or changed request, indicating the
availability of the server.
userId (1)
const char* userId() const
Returns the user ID held by the CclConn object, padded with spaces, or
blanks if none.
userId (2)
void userId(Ccl::Bool unpadded)
unpadded
Ccl::Yes
returns a null terminated string of the stored userid with no space
padding in the string.
Ccl::No
returns the string padded with spaces exactly as invoking the
userId method with no parameters.
verifyPassword
CclSecAttr* verifyPassword()
Allows a Client application to verify that the password held in the CclConn
object matches the password recorded by an external security manager for the
userid held in the CclConn object. The external security manager is assumed
to be located in the server defined by the CclConn object.
Enumerations
ServerStatus
Indicates the availability of the server. Possible values are:
unknown
The server status is unknown.
available
The server is available.
60 CICS Transaction Gateway: Programming Reference

unavailable
The server is not available.
CclECI class
Only one instance of the CclECI class can exist. It is created by the instance
class method. It controls the client interface to the available servers.
CclECI should be sub-classed to implement your own handleException
method.
Only one instance of a CclECI subclass can exist. Any attempt to create more
than one raises a multipleInstance exception.
A CclECI object cannot be copied or assigned.
CclECI constructor (protected)
CclECI()
This constructor is protected and can be accessed only from a subclass.
Public methods
exCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
Ccl::ExCode exCode() const
Returns an enumeration indicating the most recent exception code. The
possible values are listed under Table 20 on page 199.
exCodeText
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
const char* exCodeText() const
Returns a text string describing the most recent exception code.
C++ Class: CclConn
Chapter 3. C++ 61

C++ Class: CclECI
handleException
virtual void handleException(CclException &except)
except
A CclException object that contains information about the exception just
raised.
This method is called whenever an exception is raised. To deal with
exceptions, you should always subclass CclECI, and provide your own
implementation of handleException. See Handling Exceptions in the CICS
Transaction Gateway: Programming Guide. The default implementation merely
throws the exception object.
instance
static CclECI* instance()
A class method that returns a pointer to the single CclECI object that exists on
the client. Here is an example of its use:
CclECI* pmgr = CclECI::instance();
listState
const char* listState() const
Returns a formatted string containing the current state of the object. For
example:
ECI state..&CclECI=00203AE0 &CclECII=00203B20
retCode=0 exCode=0
serverCount=0 &serverBuffer=00000000
serverCount
unsigned short serverCount() const
Returns the number of available servers to which the CICS Transaction
Gateway may be connected, as configured in the CICS Transaction Gateway
initialization file. In practice, some or all of these servers may not be available.
See Finding potential servers in the CICS Transaction Gateway: Programming
Guide.
serverDesc
const char* serverDesc(unsigned short index = 1) const
index
The index of a connected server in the list. The default index is 1.
62 CICS Transaction Gateway: Programming Reference

CclEPI class
Returns the description of the indexth server. See Finding potential servers in the
CICS Transaction Gateway: Programming Guide.
serverName
const char* serverName(unsigned short index = 1) const
index
The index of a connected server in the list. The default index is 1.
Returns the name of the indexth server. See Finding potential servers in the CICS
Transaction Gateway: Programming Guide.
The CclEPI class initializes and terminates the CICS Transaction Gateway EPI
function. It also has methods which allow you to obtain information about
CICS servers configured in the CICS Transaction Gateway initialization file.
You must create one object of this class for each application process before
you create CclTerminal objects to connect to CICS servers.
CclEPI constructor
CclEPI()
This method initializes the CICS EPI interface on the client. An initEPI
exception is raised if initialization fails. Initialization of the CICS Transaction
Gateway EPI is synchronous. In other words, initialization is complete when
the call to the CclEPI constructor returns.
Public methods
diagnose
const char* diagnose() const
Returns a character string that holds a description of the condition returned
by the most recent server call.
exCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
Ccl::ExCode exCode() const
C++ Class: CclECI
Chapter 3. C++ 63

C++ Class: CclEPI
Returns an enumeration indicating the most recent exception code. The
possible values are listed under Table 20 on page 199.
exCodeText
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
const char* exCodeText() const
Returns a text string describing the most recent exception code.
handleException
virtual void handleException(CclException &except)
except
A CclException object that contains information about the exception just
raised.
This method is called whenever an exception is raised. To deal with
exceptions, use try...catch, or subclass CclEPI and provide your own
implementation of handleException. The default implementation merely
throws the exception object.
serverCount
unsigned short serverCount()
Returns the number of available servers to which the CICS Transaction
Gateway may be connected, as configured in the CICS Transaction Gateway
initialization file.
serverDesc
const char* serverDesc(unsigned short index =1)
index
The index of a configured server
Returns a description of the selected CICS server, or NULL if no information
is available in the CICS Transaction Gateway initialization file for the specified
server. If the index exceeds the number of servers configured, a maxServers
exception is raised.
64 CICS Transaction Gateway: Programming Reference

serverName
const char* serverName(unsigned short index =1)
index
The index of a configured server
Returns the name of the requested CICS server, or NULL if no information is
available in the CICS Transaction Gateway initialization file for the specified
server. If the index exceeds the number of servers configured, a maxServers
exception is raised.
state
State state() const
Returns an enumeration indicating the state of the EPI. Possible values are:
active
EPI has been initialized successfully
discon
EPI has terminated
error
EPI initialization has failed
terminate
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
void terminate()
Terminates the CICS Transaction Gateway EPI in a controlled manner. The
CclEPI object remains in existence, so that anything which occurs during the
termination can be monitored by the application.
Because the terminate method is invoked during CclEPI object destruction,
you do not need to invoke this method.
Enumerations
State
C++ Class: CclEPI
An enumeration indicating the state of the EPI. Possible values are:
active EPI has been initialized successfully
discon EPI has terminated
Chapter 3. C++ 65

C++ Class: CclEPI
CclException class
error EPI initialization has failed
A CICS Transaction Gateway object constructs an object of the CclException
class if it encounters a problem.
To deal with such a problem, you should subclass the CclECI or CclEPI class
and provide your own implementation of the handleException method. See
Handling Exceptions in the CICS Transaction Gateway: Programming Guide. This
method has access to the methods of the CclException object and can be
coded to take whatever action is necessary. For example, it can stop the
program or display a dialog box.
Alternatively, you can use a C++ try...catch block to handle exceptions.
A CclException object cannot be assigned and its constructors are intended for
use by the CICS Transaction Gateway class implementation only.
Public methods
abendCode
const char* abendCode()
Returns a null-terminated string containing the ECI abend code, or blanks if
no abend code is available.
className
const char* className() const
Returns the name of the class in which the exception was raised.
diagnose
const char* diagnose() const
Returns text explaining the exception for use in diagnostic output, for
example:
unknown server, classname=CclFlowI, methodName=afterReply, originCode=13
"link", flowId=2, retCode=-22, abendCode=" "
66 CICS Transaction Gateway: Programming Reference

exCode
Ccl::ExCode exCode() const
Returns the exception code. See Table 20 on page 199.
exCodeText
const char* exCodeText() const
Returns a text string that describes the exception code.
exObject
void* exObject() const
This method is relevant to to both the ECI and EPI.
exObject returns a pointer to the object controlling any server interaction at
the time of the exception. If there was no such object, a null pointer is
returned.
v In the case of ECI the pointer should be cast to a CclFlow*. For example:
CclFlow* pflo = (CclFlow*) ex.exObject();
v In the case of EPI exObject returns the relevant CclTerminal object pointer
in the exception block. Cast this to a CclTerminal*; for example:
CclTerminal* pTerm = (CclFlow*)ex.exObject();
methodName
const char* methodName() const
Returns the name of the method in which the exception was raised.
CclField class
An object of the CclField class is responsible for looking after a single field on
a 3270 screen. CclField objects are created and deleted when 3270 data from
the CICS server is processed by a CclScreen object.
Methods in this class allow field text and attributes to be read and updated.
Modified fields are sent to the CICS server on the next send.
Public methods
appendText (1)
void appendText(const char* text, unsigned short length)
C++ Class: CclException
Chapter 3. C++ 67

C++ Class: CclField
text
The text to be appended to the field
length
The number of characters to be appended to the field
Appends length characters from text to the end of the text already in the field.
appendText (2)
void appendText(const char* text)
text
The null-terminated text string to be appended to the field
Appends the characters within the text string to the end of the text already in
the field.
backgroundColor
Color backgroundColor() const
Returns an enumeration indicating the background color of the field. The
possible values are shown under Color at the end of the description of this
class.
baseAttribute
char baseAttribute() const
Returns the 3270 base attribute of the field.
column
unsigned short column() const
Returns the column number of the position of the start of the field on the
screen, with the leftmost column being 1.
dataTag
BaseMDT dataTag() const
Returns an enumeration indicating whether the data in the field has been
modified. Possible values are:
modified
unmodified
68 CICS Transaction Gateway: Programming Reference

foregroundColor
Color foregroundColor() const
Returns an enumeration indicating the foreground color of the field. The
possible values are shown under Color at the end of the description of this
class.
highlight
Highlight highlight() const
Returns an enumeration indicating which type of highlight is being used. The
possible values are shown under Highlight at the end of the description of
this class.
inputProt
BaseProt inputProt() const
Returns an enumeration indicating whether the field is protected. Possible
values are:
protect
unprotect
inputType
BaseType inputType() const
Returns an enumeration indicating the input data type for this field. Possible
values are:
alphanumeric
numeric
intensity
BaseInts intensity() const
Returns an enumeration indicating the field intensity. Possible values are :
dark
normal
intense
length
unsigned short length() const
C++ Class: CclField
Chapter 3. C++ 69

C++ Class: CclField
Returns the total length of the field. This includes one byte used to store the
3270 attribute byte information. The actual space for data is one byte less than
the value returned by this method. See also the textLength method.
position
unsigned short position() const
Returns the position of the start of the field on the screen, given by position =
column number + (n x row number), where n is the number of columns in a
row (usually 80).
resetDataTag
void resetDataTag()
Resets the modified data tag (MDT) to unmodified.
row
unsigned short row() const
Returns the row number of the position of the start of the field on the screen.
The top row is 1.
setBaseAttribute
void setBaseAttribute(char attribute)
attribute
The value of the base 3270 attribute byte to be entered into the field
Sets the 3270 base attribute.
setExtAttribute
void setExtAttribute(char attribute, char value)
attribute
The type of extended attribute being set
value
The value of the extended attribute
Sets an extended 3270 attribute. If an invalid 3270 attribute type or value is
supplied, a parameter exception is raised.
70 CICS Transaction Gateway: Programming Reference

setText (1)
These methods update the field with the given text.
void setText(const char* text, unsigned short length)
text
The text to be entered into the field
length
The number of characters to be entered into the field
Copies length characters from text into the field.
setText (2)
void setText(const char* text)
text
The null-terminated text to be entered into the field
Copies text, without the terminating null, into the field.
text
const char* text() const
Returns the text currently held in the field.
textLength
unsigned short textLength() const
Returns the number of characters currently held in the field.
transparency
Transparency transparency() const
Returns an enumeration indicating the background transparency of the field.
Possible values are shown under Transparency at the end of the description of
this class.
Enumerations
BaseInts
Indicates the field intensity. Possible values are:
normal
intense
dark
C++ Class: CclField
Chapter 3. C++ 71

C++ Class: CclField
BaseMDT
Indicates whether data in the field has been modified. Possible values are:
unmodified
modified
BaseProt
Indicates whether the field is protected. Possible values are:
protect
unprotect
BaseType
Indicates field input data type. Possible values are:
alphanumeric
numeric
Color
Possible values are:
defaultColor yellow paleGreen
blue neutral paleCyan
red black gray
pink darkBlue white
green orange
cyan purple
Highlight
Indicates which type of highlight is being used. Possible values are:
defaultHlt blinkHlt underscoreHlt
normalHlt reverseHlt intenseHlt
Transparency
Indicates the background transparency of the field. Possible values are:
defaultTran
default transparency
orTran
OR with underlying color
xorTran
XOR with underlying color
72 CICS Transaction Gateway: Programming Reference

opaqueTran
opaque
CclFlow class
A CclFlow object is used to control ECI communications for a client/server
pair and to determine the synchronization of reply processing. Refer to
Compiling and Linking in the CICS Transaction Gateway: Programming Guide for
an explanation of synchronization. CclFlow automatically calls its
handleReply method when a reply is available; this simplifies control of
interleaved replies. Subclass CclFlow to implement your own handleReply
method.
A CclFlow object is created for each client/server interaction (request from
client and response from server). CclFlow objects can be reused when they
become inactive, that is, when reply processing is complete. An attempt to
delete or reuse an active CclFlow object raises an activeFlow exception.
CclFlow constructor
CclFlow (1)
CclFlow(Ccl::Sync syncType, unsigned long stackPages =3)
syncType
The type of synchronization
stackPages
If asynchronous, the number of 4kb stack pages. The default is 3. If not
asynchronous, this parameter is ignored.
CclFlow (2)
C++ Class: CclField
CclFlow(Ccl::Sync syncType,
unsigned long stackPages,
const unsigned short &timeout)
syncType
The type of synchronization
stackPages
If asynchronous, the number of 4kb stack pages. If not asynchronous, this
parameter is ignored.
timeout
The time in seconds to wait for the ECI program to respond. If a timeout
occurs, the HandleException method is called with a timeout CclException
Object. Valid values are 0-32767.
Chapter 3. C++ 73

C++ Class: CclFlow
Public methods
abendCode
const char* abendCode() const
Returns the abend code from the most recently executed CICS transaction, or
blank if there have been none.
callType
CallType callType() const
Returns an enumeration value indicating the most recent type of server
request.
callTypeText
const char* callTypeText() const
Returns the name of the most recent server request.
connection
CclConn* connection() const
Returns a pointer to the CclConn object that represents the server being used,
if any, or zeros.
diagnose
const char* diagnose() const
Returns text explaining the exception for use in diagnostic output; for
example:
"link", flowId=2, retCode=-22, abendCode=" "
flowId
unsigned short flowId() const
Returns the unique identity of this CclFlow object.
forceReset
void forceReset()
74 CICS Transaction Gateway: Programming Reference

Makes the flow inactive and resets it. This is typically used to prepare a
CclFlow object for re-use or deletion after a flow has been abandoned, for
example when a C++ throw is used in a exception handler. This applies only
to dsync and async flows. You cannot issue this on a sync call from another
thread.
handleReply
virtual void handleReply(CclBuf* commarea)
commarea
A pointer to the CclBuf object containing the returned COMMAREA or
zero if none.
This method is called whenever a reply is received from a server, irrespective
of the type of synchronization or the type of call. See Compiling and Linking in
the CICS Transaction Gateway: Programming Guide. To deal with replies, you
should subclass CclFlow and provide your own implementation of
handleReply. The default implementation merely returns to the caller.
listState
const char* listState() const
Returns a formatted string containing the current state of the object. For
example:
Flow state..&CclFlow=000489A4 &CclFlowI=00203B70
syncType=2 threadId=0 stackPages=9 callType=0 flowId=0 commLength=0
retCode=0 systemRC=0 abendCode=" " &CclConnI=00000000 &CclUOWI=00000000
poll
C++ Class: CclFlow
Ccl::Bool poll(CclBuf* commarea =0)
commarea
An optional pointer to the CclBuf object that will be used to contain the
returned COMMAREA.
Returns an enumeration, defined within the Ccl class indicating whether a
reply has been received from a deferred synchronous Backout, Cancel,
Changed, Commit, Link, orStatus call request. If poll is used on a flow
object that is not deferred synchronous, a syncType exception is raised.
Possible values are:
yes A reply has been received. handleReply has been called
synchronously.
no No reply has been received. The client process is not blocked.
Chapter 3. C++ 75

C++ Class: CclFlow
setTimeout
void setTimeout(const unsigned short &timeout)
timeout
the defined time in seconds to wait for the ECI program to respond. If a
timeout occurs, the HandleException method is called with a timeout
CclException Object. Valid values are 0-32767.
Sets the timeout value for the flow object for the next activation of the flow.
This value can be set while a flow is active but does not affect the current
active flow
syncType
Ccl::Sync syncType() const
Returns an enumeration, defined within the Ccl class indicating the type of
synchronization being used. Possible values are shown in “Sync” on page 49.
timeout
short timeout()
Retrieves the current timeout value set for the flow object.
uow
CclUOW* uow() const
Returns a pointer to any CclUOW object containing information on any units
of work (UOWs) associated with this interaction.
wait
void wait()
Waits for a reply from the server, blocking the client process in the meantime.
If wait is used on a synchronous flow object, a syncType exception is raised.
Enumerations
CallType
The possible values for server requests in progress under the control of a
CclFlow object are:
inactive
No server call is currently in progress
76 CICS Transaction Gateway: Programming Reference

CclMap class
link
A CclConn::link call to a server program
backout
A CclUOW::backout call to back out changes made to recoverable
resources on the server
commit
A CclUOW::commit call to commit changes made to recoverable
resources on the server
status
A CclConn::status call to determine the status of a server connection
changed
A CclConn::changed call to request notification when the status of a
connection to a server changes
cancel
A CclConn::cancel call to cancel an earlier CclConn::changed request.
The CclMap class is a base class for map classes created by the CICS BMS
Map Conversion Utility. The methods provided by CclMap class are inherited
by the classes generated from BMS maps.
CclMap constructor
CclMap(CclScreen* screen)
screen
A pointer to the matching CclScreen object.
Creates a CclMap object and checks (validates) that the map matches the
content of the screen, defined by the CclScreen object. If validation was
unsuccessful, an invalidMap exception is raised. If the supplied CclScreen
object is invalid, a parameter exception is raised.
Public methods
exCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
Ccl::ExCode exCode() const
C++ Class: CclFlow
Returns an enumeration indicating the most recent exception code. The
possible values are listed in Table 20 on page 199.
Chapter 3. C++ 77

C++ Class: CclMap
exCodeText
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
const char* exCodeText() const
Returns a text string describing the most recent exception code.
field (1)
CclField* field(unsigned short index)
index
The index number of the required CclField object.
Returns a pointer to the CclField object identified by index in the BMS map.
field (2)
CclField* field(unsigned short row, unsigned short column)
row
The row number of the required CclField object within the map. The top
rowis1.
column
The column number of the required CclField object within the map. The
left column is 1.
Returns a pointer to the CclField object identified by position in the BMS
map.
Protected methods
namedField
CclField* namedField(unsigned long index)
index
The index number of the required CclField object.
Returns the address of the indexth object.
validate
void validate(const MapData* map,
const FieldIndex* index,
const FieldData* fields)
78 CICS Transaction Gateway: Programming Reference

map
A structure that contains information about the map. The structure is
defined within this class and contains the following members, which are
all unsigned short integers:
row Map row position on screen
col Map column position on screen
width Map width in columns
depth Map depth in rows
fields Number of fields
labels Number of labeled fields
index
The index number of the required CclField object. FieldIndex is a typedef
of this class and is equivalent to an unsigned short integer.
fields
A structure that contains information about a particular field. The
structure is defined within this class and contains the following members,
which are all unsigned short integers:
row Field row (within map)
col Field column (within map)
len Field length
Validate map against the current screen.
CclScreen class
The CclScreen EPI class maintains all data on the 3270 virtual screen and
provides access to this data. It contains a collection of CclField objects which
represent the fields on the current 3270 screen.
A single CclScreen object is created by the CclTerminal object; use the screen
method on the CclTerminal object to obtain it. The CclScreen object is updated
by the CclTerminal object when 3270 data is received from CICS. A
dataStream exception is raised if an unsupported datastream is received.
Public methods
cursorCol
unsigned short cursorCol() const
Returns the column number of the current position of the cursor. The left
column is 1.
cursorRow
unsigned short cursorRow() const
C++ Class: CclMap
Chapter 3. C++ 79

C++ Class: CclScreen
Returns the row number of the current position of the cursor. The top row is
1.
depth
unsigned short depth() const
Returns the number of rows in the screen.
field (1)
These methods allow you to access fields on the current screen by returning a
pointer to the relevant CclField object.
CclField* field(unsigned short index)
index
The index number of the field of interest
field (2)
CclField* field(unsigned short row, unsigned short column)
row
The row number of the field
column
The column number of the field
fieldCount
unsigned short fieldCount() const
Returns the number of fields in the screen.
mapName
const char* mapName()
Returns a padded null terminated string specifying the name of the map that
was most recently referenced in the MAP option of a SEND MAP command
processed for the terminal resource. If the terminal resource is not supported
by BMS, or the server has no record of any map being sent, the value
returned is spaces.
mapSetName
const char* mapSetName()
80 CICS Transaction Gateway: Programming Reference

Returns a padded null terminated string specifying the name of the mapset
that was most recently referenced in the MAPSET option of a SEND MAP
command processed for the terminal resource. If the MAPSET option was not
specified on the most recent request, BMS used the map name as the mapset
name. In both cases, the mapset name used may have been suffixed by a
terminal suffix. If the terminal resource is not supported by BMS, or the server
has no record of any mapset being sent, the value returned is spaces.
setAID
void setAID(const AID key)
key
An AID key. See the AID enumerations at the end of this chapter.
Sets the AID key value to be passed to the server on the next transmission.
setCursor
void setCursor(unsigned short row, unsigned short col)
row
The required row number of the cursor. The top row is 1.
col
The required column number of the cursor. The left column is 1.
Requests that the cursor position be set. If the supplied row or column values
are outside the screen boundaries, a parameter exception is raised.
width
unsigned short width() const
Returns the number of columns on the screen.
Enumerations
AID
Indicates an AID key. Possible values are:
enter
clear
PA1—PA3
PF1—PF24
C++ Class: CclScreen
Chapter 3. C++ 81

C++ Class: CclScreen
CclSecAttr
CclSecTime
The CclSecAttr class provides information about passwords reported back by
the external security manager when verifyPassword or changePassword
methods are issued on CclConn or CclTerminal objects.
This object is created and owned by the CclConn or CclTerminal Object;
access to this object is provided when the verifyPassword or changePassword
methods are invoked.
Public Methods
expiryTime
CclSecTime* expiryTime() const
Returns a CclSecTime object that contains the Date and Time at which the
password will expire
invalidCount
unsigned short invalidCount() const
Returns the Number of times that an invalid password has been entered for
the userid.
lastAccessTime
CclSecTime* lastAccessTime() const
Returns a CclSecTime object that contains the date and time when the userid
was last accessed.
lastVerifiedTime
CclSecTime* lastVerifiedTime() const
Returns a CclSecTime object that contains the date and time of the Last
Verification.
The CclSecTime class provides date and time information in the CclSecAttr
object for various entries reported back by the external security manager
when verifyPassword or changePassword methods are issued on CclConn or
CclTerminal objects.
82 CICS Transaction Gateway: Programming Reference

These objects are created and owned by the CclSecAttr object and access is
obtained via the various methods available on this object. No Constructors or
Destructors are available.
Public Methods
day
unsigned short day() const
Returns the day with a range from 1 to 31; 1 represents the first day of the
month.
get_time_t
time_t get_time_t() const
Returns the date and time in a time_t format.
get_tm
tm get_tm() const
Returns the date and time in a tm structure.
hours
unsigned short hours() const
Returns the hours with a range from 0 to 23.
hundredths
unsigned short hundredths() const
Returns the hundredths of seconds with a range from 0 to 99.
minutes
unsigned short minutes() const
Returns the minutes with a range from 0 to 59.
month
unsigned short month() const
Returns the month with a range from 1 to 12. January is 1.
C++ Class: CclScreen
Chapter 3. C++ 83

C++ Class: CclScreen
seconds
unsigned short seconds() const
Returns the seconds with a range from 0 to 59.
year
unsigned short year() const
Returns a 4–digit year
CclSession class
The CclSession class allows the programmer to implement reusable code to
handle a segment (one or more transmissions) of a 3270 conversation. In
multi-threaded environments it provides asynchronous handling of replies
from CICS.
The CclSession class controls the flow of data to and from CICS within a
single 3270 session. You should derive your own classes from CclSession.
CclSession constructor
CclSession(Ccl::Sync syncType)
syncType
The protocol to be used on transmissions to the CICS server. Possible
values are:
async asynchronous
dsync deferred synchronous
sync synchronous
Public methods
diagnose
const char* diagnose() const
Returns a text description of the last error.
handleReply
virtual void handleReply(State state, CclScreen* screen)
state
An enumeration indicating the state of the data flow. The scope of the
values is shown under State at the end of the description of this class.
screen
A pointer to the CclScreen object.
84 CICS Transaction Gateway: Programming Reference

This is a virtual method which you can override when you develop your own
class derived from CclSession. It is called when data is received from CICS.
state
State state() const
Returns an enumeration indicating the current state of the session. Possible
values are shown under State at the end of the description of this class.
terminal
CclTerminal* terminal() const
Returns a pointer to the CclTerminal object for this session. This method
returns a NULL pointer until the CclSession object has been associated with a
CclTerminal object (that is, until the CclSession object has been used as a
parameter on a CclTerminal send method).
transID
const char* transID() const
Returns the 4-letter name of the current transaction.
Enumerations
State
C++ Class: CclSession
Indicates the state of a session. Possible values are:
idle
The terminal is connected and no CICS transaction is in progress.
server
A CICS transaction is in progress in the server.
client
A CICS transaction is in progress, and the server is waiting for a response
from the client.
discon
The terminal is disconnected.
error
There is an error in the terminal.
Chapter 3. C++ 85

|
|
C++ Class: CclTerminal
CclTerminal class
An object of class CclTerminal represents a 3270 terminal connection to a
CICS server. A CICS connection is established when the object is created.
Methods can then be used to converse with a 3270 terminal application (often
a BMS application) in the CICS server.
The EPI must be initialized (that is, a CclEPI object created) before a
CclTerminal object can be created.
The CclTerminal class destructor does not purge ATI requests queued against
the terminal.
CclTerminal constructor
CclTerminal (1)
CclTerminal(const char* server = NULL,
const char* devtype = NULL,
const char* netname = NULL)
server
The name of the server with which you want to communicate. If no name
is provided the default server system is assumed. The length is adjusted
to 8 characters by padding with blanks.
devtype
The name of the model terminal definition that the server uses to generate
a terminal resource definition. If no string is provided the default model is
used. The length is adjusted to 16 characters by padding with blanks.
netname
The name of the terminal resource to be installed or reserved. The default
is to use the contents of devtype. The length is adjusted to 8 characters by
padding with blanks.
Creates the CclTerminal object that is used for EPI communication between
the client and server.
This constructor does an implicit install terminal. You do not need to invoke
the install method if you construct a terminal object this way.
If the named server is not configured in the CICS Transaction Gateway
initialization file, an unknownServer exception is raised.
If invalid values are supplied for server, devtype or netname, a parameter
exception is raised.
If a CclEPI object has not been created, an initEPI exception is raised.
86 CICS Transaction Gateway: Programming Reference

If the maximum number of supported terminal connections has been
exceeded, a maxRequests exception is raised.
CclTerminal (2)
C++ Class: CclTerminal
CclTerminal(const char* server,
const char* devtype,
const char* netname,
signonType signonCapability
const char* userid
const char* password
const unsigned short &readTimeOut,
const unsigned short &CCSid)
server
The name of the server with which you want to communicate. If no name
is provided the default server system is assumed. The length is adjusted
to 8 characters by padding with blanks.
devtype
The name of the model terminal definition which the server uses to
generate a terminal resource definition. If no string is provided the default
model is used. The length is adjusted to 16 characters by padding with
blanks.
netname
The name of the terminal resource to be installed or reserved. The default
is to use the contents of devtype. The length is adjusted to 8 characters by
padding with blanks.
signonCapability
Sets the type of signon capability for the terminal.
Possible values are:
CclTerminal::SignonCapable
CclTerminal::SignonIncapable
userid
The name of the userid to associate with this terminal resource
password
The password to associate with the userid
readTimeOut
A value in the range 0 through 3600, specifying the maximum time in
seconds between the time the classes go clientrepl state and the
application program invokes the reply method.
CCSid
An unsigned short specifying the coded character set identifier (CCSID)
that identifies the coded graphic character set used by the Client
application for data passed between the terminal resource and CICS
transactions. A zero string means that a default will be used.
Chapter 3. C++ 87

C++ Class: CclTerminal
Creates a Terminal object that does not do an implicit install terminal. You
must run the install method to install the terminal.
Public methods
alterSecurity
void alterSecurity(const char* userid,const char* password)
userid
The new userid
password
The new password for userid
Allows you to re-define the userid and password for a terminal resource. You
may call the method before you install a terminal. It changes only the
terminal definition; the new userid and password will be used for the
terminal when install is called.
changePassword
CclSecAttr* changePassword(const char* newPassword)
newPassword
The new password
Allows a Client application to change the password held in the terminal object
and the password recorded by an external security manager for the userid
held in the terminal object. The external security manager is assumed to be
located in the server defined by the terminal object.
CCSid
unsigned short CCSid()
Returns the selected code page as an unsigned short.
diagnose
const char* diagnose()
Returns a character string that holds a description of the error returned by the
most recent server call.
disconnect (1)
void disconnect()
88 CICS Transaction Gateway: Programming Reference

Disconnects the terminal from CICS. No attempt is made to purge any
outstanding running transaction.
disconnect (2)
void disconnect(Ccl::Bool withPurge)
withPurge
Ccl::Yes
Disconnects the terminal from CICS and attempts to purge any
outstanding running transaction. This purge function does not
cancel ATI requests queued against the terminal.
Ccl::No
Disconnects the terminal from CICS. No attempt is made to purge
outstanding running transactions.
discReason
void discReason(void)
Returns the reasons for a disconnection. See “EndTerminalReason” on page 95.
exCode
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
Ccl::ExCode exCode() const
Returns an enumeration indicating the most recent exception code. The
possible values are listed in Table 20 on page 199.
exCodeText
Deprecated method
Do not use this method in new applications. The method has been
deprecated and is provided only for compatibility.
const char* exCodeText() const
Returns a text string describing the most recent exception code.
C++ Class: CclTerminal
Chapter 3. C++ 89

C++ Class: CclTerminal
install
void install(CclSession *session,
const unsigned short &installTimeOut)
session
A pointer to the CclSession object that is to be used for the CICS server
interaction.
installTimeOut
A value in the range 0 to 3600, specifying the maximum time in seconds
that installation of the terminal resource is allowed to take. A value of 0
means that no limit is set.
Connects a non-connected terminal resource. Throws an invalidState error if
already connected, or a timeout error if a timeout occurs.
makeSecurityDefault
void makeSecurityDefault()
Informs the client that the current userid and password for this object are to
become the default for ECI and EPI requests passed to the server as specified
in the construction of the Terminal object.
netName
const char* netName() const
Returns the network name of the terminal as a null terminated string.
password
const char* password()
Returns a null terminated string containing the current password setting for
the terminal, or null if the terminal has no password.
poll
Ccl::Bool poll()
Polls for data from the CICS server.
For deferred synchronous transmissions (that is, if a deferred synchronous
CclSession object was used on a previous send call) the poll method is called
by the application when it wants to receive data from the CICS server. If a
reply from CICS is ready, the CclTerminal object updates the CclScreen object
90 CICS Transaction Gateway: Programming Reference

with the contents of the 3270 datastream received from CICS, the
handleReply virtual function on the CclSession object is called, and the poll
method returns Ccl::yes. If no reply has been received from CICS, the poll
method returns Ccl::no.
The poll method is used only for deferred synchronous transmissions; a
syncType exception is raised if the poll method is called when a synchronous
or asynchronous session is in use. An invalidState exception is raised if the
poll method is called when there was no previous send call. The CclTerminal
object should be in server state for poll to be called.
A CICS server transaction may send more than one reply in response to a
CclTerminal send call. More than one CclTerminal poll call may therefore be
needed to collect all the replies. Use the CclTerminal state method to find out
if further replies are expected. If there are, the value returned will be server.
See EPI call synchronization types in the CICS Transaction Gateway: Programming
Guide.
queryATI
ATIState queryATI()
Returns an enumeration indicating whether the “Automatic Transaction
Initiation” (ATI) is enabled or disabled. Possible values are:
disabled
enabled
readTimeout
const char* readTimeout()
Returns the read timout value for the terminal as a null terminated string .
receiveATI
C++ Class: CclTerminal
void receiveATI(CclSession* session)
session
pointer to the CclSession object that is to be used for the CICS server
interaction.
Waits for and receives 3270 datastream for a CICS ATI transaction. The
CclSession object supplied as a parameter determines whether the call is
synchronous or asynchronous, and can be subclassed to provide a reply
handler
Chapter 3. C++ 91

C++ Class: CclTerminal
screen
CclScreen* screen() const
Returns a pointer to the CclScreen object that is handling the 3270 screen
associated with this terminal session.
send (1)
void send(CclSession* session,
const char* transid,
const char* startdata = NULL)
session
A pointer to the CclSession object that controls the session which is to be
used. If no valid CclSession object is supplied, a parameter exception is
raised.
transid
The name of the transaction which is to be started
startdata
start transaction data. The default is to have no data for the transaction
being started.
Formats and sends a 3270 datastream, starting the named transaction. The
CclTerminal object must be in idle state (connected to a CICS server but with
no transaction in progress). If the object is not in idle state, an invalidState
exception is raised.
send (2)
void send(CclSession* session)
The session parameter is described above.
Formats and sends a 3270 datastream. The CclTerminal object must be in idle
state (see above) or in client state (that is, with a transaction in progress and
the CICS server waiting for a response). If the object is not in idle or client
state, an invalidState exception is raised.
setATI
void setATI(ATIState newstate)
newstate
An enumeration indicating whether the ATI is to be enabled or disabled.
The scope of the values is within this class and the possible values are
disabled and enabled.
92 CICS Transaction Gateway: Programming Reference

signonCapability
signonType signonCapability()
Returns the type of signon capability applied to the terminal at installation.
Possible values are:
CclTerminal::signonCapable
CclTerminal::signonIncapable
CclTerminal::signonUnknown
state
State state() const
Returns an enumeration indicating the current state of the session. Possible
values are shown at the end of the description of this class.
serverName
const char* serverName() const
Returns the name of the CICS server to which this terminal session is
connected.
termID
const char* termID() const
Returns the 4-character terminal ID.
transID
const char* transID() const
Returns the 4-character name of the current CICS transaction. If a RETURN
IMMEDIATE is run from the current transaction, TransId does not provide the
name of the new transaction; it still contains the name of the first transaction.
userId
const char* userId()
C++ Class: CclTerminal
Returns a null terminated string containing the current userid setting for the
terminal, Null if none.
Chapter 3. C++ 93

|
|
|
C++ Class: CclTerminal
verifyPassword
CclSecAttr* verifyPassword()
Allows a Client application to verify that the password held in the terminal
object matches the password recorded by an external security manager for the
userid held in the terminal object. The external security manager is assumed
to be located in the server defined by the terminal object.
Enumerations
ATIState
Indicates whether “Automatic Transaction Initiation” (ATI) is enabled or
disabled. Possible values are:
enabled
disabled
signonType
Indicates the signon capability of a terminal. Possible values are:
signonCapable
Signon Capable
signonIncapable
Signon Incapable
signonUnknown
Signon Unknown
State
Indicates the state of the CclTerminal object. Possible values are:
client
A CICS transaction is in progress and the server is waiting for a response
from the client.
discon
The terminal is disconnected.
error
There is an error in the terminal.
idle
The terminal is connected and no CICS transaction is in progress.
server
A CICS transaction is in progress in the server.
termDefined
A terminal has been defined but not installed.
txnTimedOut
A conversational transaction has timed out, but the END_TRAN event
has not been retrieved. For synchronous and asynchronous terminals the
94 CICS Transaction Gateway: Programming Reference

|
|
|
|
terminal method blocks until the event has been received and the
terminal becomes idle. For deferred synchronous terminals it indicates
that a poll() needs to be done to get the event. This resets the terminal to
the idle state; handleException() and handleReply() are not invoked.
EndTerminalReason
Indicates the EndTerminalReason of the CclTerminal object. Possible values
are:
signoff
A disconnect was requested or the user has signed off the terminal.
shutdown
The CICS server has been shutdown.
outofService
The terminal has been switched to out of service.
unknown
An unknown situation has occurred.
failed
The terminal failed to disconnect.
notDiscon
The terminal is not disconnected.
CclUOW class
Use this ECI class when you make updates to recoverable resources in the
server within a “unit of work” (UOW). Each update in a UOW is identified at
the client by a reference to its CclUOW—see link in CclConn (“link” on
page 57).
A CclUOW object cannot be copied or assigned. An attempt to delete a
CclUOW object for which there is an active CclFlow object raises an
activeFlow exception. Any attempt to delete an active CclUOW object, that is
one which has not been committed or backed out, raises an activeUOW
exception.
CclUOW constructor
CclUOW()
Creates a CclUOW object.
Public methods
backout
void backout(CclFlow& flow)
C++ Class: CclTerminal
Chapter 3. C++ 95

C++ Class: CclUOW
flow
A reference to the CclFlow object that is used to control the client/server
call
Terminate this UOW and back out all changes made to recoverable resources
in the server.
commit
void commit(CclFlow& flow)
flow
A reference to the CclFlow object that is used to control the client/server
call
Terminate this UOW and commit all changes made to recoverable resources in
the server.
forceReset
void forceReset()
Make this UOW inactive and reset it.
listState
const char* listState() const
Returns a zero-terminated formatted string containing the current state of the
object. For example:
UOW state..&CclUOW=0004899C &CclUOWI=00203BD0
&CclConnI=00000000 uowId=0 &CclFlowI=00000000
uowId
unsigned long uowId() const
Returns the identifier of the UOW. 0 means that the UOW is either complete
or has not yet started. In other words, it is inactive.
96 CICS Transaction Gateway: Programming Reference

Chapter 4. C and COBOL
External Call Interface
CICS_ExternalCall ECI_Parms
Purpose
CICS_ExternalCall gives access to the program link calls, status information
calls, and reply solicitation calls. The function performed is controlled by the
eci_call_type field in the ECI parameter block.
Parameters
ECI_Parms
A pointer to the ECI parameter block. Set the parameter block to nulls
before use. The parameter block fields that are used as input and
output are described in detail for each call type in the following
sections. A brief summary of the fields follows:
eci_call_type
An integer field defining the type of call being made. For
details of the functions provided, see Types of ECI call in CICS
Transaction Gateway: Programming Guide.
eci_program_name
The name of a program to be called.
eci_userid
User ID for security checking.
eci_password
Password for security checking.
eci_transid
A transaction identifier.
eci_abend_code
Abend code for a failed program.
eci_commarea
A COMMAREA for use by a called program, or for returned
status information.
eci_commarea_length
The length of the COMMAREA. The size of the COMMAREA
must be set to the largest size of the input or output data.
This length must not exceed 32 500 bytes. If the input data is
less than the length of the COMMAREA, pad the
© Copyright IBM Corp. 1989, 2002 97

98 CICS Transaction Gateway: Programming Reference
COMMAREA with nulls. The Client daemon strips off the null
padding and sends only the data on the ECI request to the
CICS server.
eci_timeout
The time to wait for a response from the CICS server. For
more information on the ECI time-out support, see the CICS
Transaction Gateway: Programming Guide.
reserved1
A return code giving more information about an unexpected
error.
This field was previously eci_system_ return_code. In Version
3.1 and higher of the product, this field is kept for
compatibility. No information is returned in this field; all
system errors are written to the CICS Transaction Gateway’s
error log.
eci_extend_mode
A field that qualifies the function to be performed in various
ways.
eci_message_qualifier
A user-provided reference to an asynchronous call.
eci_luw_token
An identifier for a logical unit of work.
eci_sysid
Reserved for future use; leave null.
eci_version
The version of the ECI for which the application is coded. You
may use the values ECI_VERSION_1 or ECI_VERSION_1A.
All the facilities of version 1 are available in version 1A.
Facilities available only in version 1A are noted where they
occur.
eci_system_name
The name of a CICS server.
eci_callback
A pointer to a callback routine for an asynchronous request.
eci_userid2
User ID for security checking. This is used if the User ID or
password is more than 8 Characters.
eci_password2
Password for security checking. This is used if the User ID or
password is more than 8 Characters.

eci_tpn
A transaction identifier for a mirror transaction. This field is
available only when eci_version has the value
ECI_VERSION_1A.
Return Codes
In addition to the return codes described for each call type in the following
sections, the following return codes are possible.
ECI_ERR_INVALID_CALL_TYPE
The call type was not one of the valid call types.
ECI_ERR_CALL_FROM_CALLBACK
The call was made from a callback routine.
ECI_ERR_REQUEST_TIMEOUT
The time-out interval expired before the request could be processed,
or the specified interval was negative.
ECI_ERR_RESPONSE_TIMEOUT
The time-out interval expired while the program was running.
ECI_ERR_SYSTEM_ERROR
An internal system error occurred. The error might have been in the
CICS Transaction Gateway or in the server. The programmer should
save the information returned in the CICS Transaction Gateway’s error
log, as this will help service personnel to diagnose the error.
ECI_ERR_INVALID_VERSION
The value supplied for eci_version was invalid.
ECI_ERR_REQUEST_TIMEOUT
The value in the eci_timeout field of the ECI parameter block is
negative.
In some implementations, some of the return codes documented here and for
each call type will never be returned.
The mapping of actual return code values to the symbolic names is contained
in the following file for the Windows operating systems:
C \include\cics_eci.h
Cobol \copybook\cicseci.cbl
and in the following files for the UNIX operating systems:
C /include/cics_eci.h
Chapter 4. C and COBOL 99

Call types for the CICS_ExternalCall
ECI_SYNC call type
Environment: The ECI_SYNC call type is available in all environments.
Purpose: The ECI_SYNC call type provides a synchronous program link call
to start, continue, or end a logical unit of work. The calling application does
not get control back until the called CICS program has run to completion.
ECI parameter block fields: The ECI parameter block should be set to nulls
before setting the input parameter fields.
eci_call_type
Required input parameter, which must be set to ECI_SYNC.
eci_program_name
Input parameter, required except when eci_extend_mode is
ECI_COMMIT or ECI_BACKOUT. (See the Logical units of work in ECI
table in CICS Transaction Gateway: Programming Guide for more details.)
An 8-character field containing the name of the program to be called.
Pad unused characters with spaces. This field is transmitted to the
server without conversion to uppercase.
The characters used are translated from the client’s code page to an
EBCDIC code page before transmission. If the server uses an ASCII
code page, they will be retranslated. The only characters guaranteed
to be invariant under these translations are the uppercase characters A
to Z, and the numeric characters 0 to 9. Some EBCDIC servers
(Katakana and Hebrew character set A) do not use the standard
representations of the lowercase alphabetic characters; use them with
care when communicating with such servers.
eci_userid
Required input parameter.
An 8-character field containing a user ID. Pad unused characters with
spaces.
Consult the documentation for the CICS Transaction Gateway and the
server to check whether this field is converted to upper case before
being transmitted to the server. If a user ID or password longer than 8
characters is required, set eci_userid and eci_password to nulls, and
use fields eci_userid2 and eci_password2 instead.
If a user ID is supplied, the server uses the user ID and any supplied
password to authenticate the user. The supplied user ID and
password are used in subsequent security checking in the server.
100 CICS Transaction Gateway: Programming Reference

eci_password
Required input parameter.
An 8-character field containing a password. Pad unused characters
with spaces.
Consult the documentation for the CICS Transaction Gateway and the
server to check whether this field is converted to upper case before
being transmitted to the server. If a user ID or password longer than 8
characters is required, set this field and eci_userid to nulls, and use
fields eci_userid2 and eci_password2 instead.
eci_transid
Optional input parameter
A 4-character field optionally containing the ID of a CICS transaction.
Pad unused characters with spaces. The parameter is ignored if
eci_tpn is used (set to any value other than nulls). The use of this
parameter depends on the client from which the request is sent. The
value of eci_transid is converted from ASCII to EBCDIC, with no
upper case translation, and stored in EIBTRNID for the duration of
the LINK to the program specified in the eci_program_name.
The called program runs under the mirror transaction CPMI, but is
linked to under the eci_transid transaction name. This name is
available to the called program for querying the transaction ID. Some
servers use the transaction ID to determine security and performance
attributes for the called program. In those servers, you are
recommended to use this parameter to control the processing of your
called programs.
If the ECI request is extended (see the description of
eci_extend_mode), the eci_transid parameter has a meaning only for
the first call in the unit of work.
If the field is all nulls, and eci_tpn is not specified, the default server
transaction ID is used.
eci_abend_code
Output parameter.
A 4-character field in which a CICS abend code is returned if the
transaction that executes the called program abends. Unused
characters are padded with spaces.
eci_commarea
Optional input parameter.
A pointer to the data to be passed to the called CICS program as its
COMMAREA. The COMMAREA will be used by the called program
to return information to the application.
Chapter 4. C and COBOL 101

If no COMMAREA is required, supply a null pointer and set the
length (specified in eci_commarea_length) to zero.
If the code page of the application is different from the code page of
the server, data conversion must be performed at the server. To do
this, use CICS-supplied resource conversion capabilities, such as the
DFHCNV macro definitions.
eci_commarea_length
Optional input parameter.
The length of the COMMAREA in bytes. This value may not exceed
32 500. (Some client/server combinations may allow larger
COMMAREAs, but this is not guaranteed to work.)
If no COMMAREA is required, set this field to zero and supply a null
pointer in eci_commarea.
eci_timeout
The time in seconds to wait for a response from the CICS server. A
value of 0 means that no limit is set.
If timeout occurs, the conversation is abended.
reserved1
Output parameter.
This field was previously eci_system_ return_code. In the CICS
Transaction Gateway Version 3.1, and higher, this field is reserved for
backward compatibility. No information is returned in this field; all
system errors are written to the CICS Transaction Gateway’s error log.
eci_extend_mode
Required input parameter.
An integer field determining whether a logical unit of work is
terminated at the end of this call.) (See the Logical units of work in ECI
table in CICS Transaction Gateway: Programming Guide for more details.)
The values for this field (shown by their symbolic names) are as
follows:
ECI_NO_EXTEND
1. If the input eci_luw_token field is zero, this is the only
call for a logical unit of work.
2. If the input eci_luw_token field is not zero, this is the last
call for the specified logical unit of work.
102 CICS Transaction Gateway: Programming Reference
In either case, changes to recoverable resources are committed
by a CICS end-of-task syncpoint, and the logical unit of work
ends.

If you set eci_extend_mode to ECI_NO_EXTEND and
eci_luw_token to 0, you will observe one request flowing from
client to server and one reply flowing from server to client.
The server sends the reply after the program specified in
eci_program_name has been invoked and the changes made
by that program have been committed.
ECI_EXTENDED
1. If the input eci_luw_token field is zero, this is the first call
for a logical unit of work that is to be continued.
2. If the input eci_luw_token field is not zero, this call is
intended to continue the specified logical unit of work.
In either case the logical unit of work continues after the
called program completes successfully, and changes to
recoverable resources remain uncommitted.
ECI_COMMIT
Terminate the current logical unit of work, identified by the
input eci_luw_token field, and commit all changes made to
recoverable resources.
ECI_BACKOUT
Terminate the logical unit of work identified by the input
eci_luw_token field, and back out all changes made to
recoverable resources.
eci_luw_token
Required input and output parameter.
An integer field used for identifying the logical unit of work to which
a call belongs. It must be set to zero at the start of a logical unit of
work (regardless of whether the logical unit of work is going to be
extended). If the logical unit of work is to be extended, the ECI
updates eci_luw_token with a valid value on the first call of the
logical unit of work, and this value should be used as input to all
later calls related to the same logical unit of work. (See the Logical
units of work in ECI table in CICS Transaction Gateway: Programming
Guide for more details.)
If the return code is not ECI_NO_ERROR, and the call was continuing
or ending an existing logical unit of work, this field is used as output
to report the condition of the logical unit of work. If it is set to zero,
the logical unit of work has ended, and its updates have been backed
out. If it is nonzero, it is the same as the input value, the logical unit
of work is continuing, and its updates are still pending.
eci_sysid
Required input parameter.
Chapter 4. C and COBOL 103

Reserved for future use, but this field should be initialized with nulls
before the start of each logical unit of work.
eci_version
Required input parameter.
The version of the ECI for which the application is coded. You may
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the
facilities of version 1 are available in version 1A. Facilities available
only in version 1A are noted where they occur.
eci_system_name
Optional input parameter.
An 8-character field that specifies the name of the server to which the
ECI request is to be directed. Pad unused characters with spaces. If
supplied, it should be one of the server names returned by
CICS_EciListSystems. The value may be supplied whenever
eci_luw_token is set to zero. (If it is supplied when eci_luw_token is
not zero, it is ignored, because the server was established at the start
of the logical unit of work.)
If the field is set to nulls, the default server is selected; the name of
the chosen server is returned in this field, and must be used in
subsequent related ECI requests. If ECI requests made in different
logical units of work must be directed to the same server,
eci_system_name must identify that server by name.
eci_userid2
Optional input parameter.
If the eci_userid field is set to nulls, the eci_userid2 field specifies the
user ID (if any) to be used at the server for any authority validation.
The user ID can be up to 16 characters.
See the description of the eci_userid field for information about how
the user ID is used.
eci_password2
Optional input parameter.
If the eci_password field is set to nulls, the eci_password2 field
specifies the password (if any) to be used at the server for any
authority validation. The password can be up to 16 characters.
See the description of the eci_password field for information about
how the password is used.
eci_tpn
Optional input parameter. Available only if the value of eci_version is
ECI_VERSION_1A.
104 CICS Transaction Gateway: Programming Reference

A 4-character field that specifies the transaction ID of the transaction
that will be used in the server to process the ECI request. This
transaction must be defined in the server as a CICS mirror transaction.
If the field is not set, the default mirror transaction CPMI is used.
If the ECI request is extended (see the description of
eci_extend_mode), this parameter has a meaning only for the first
request.
If this field is used, the contents of eci_transid are ignored.
Return codes: See also the general list of return codes for CICS_ExternalCall
in “CICS_ExternalCall ECI_Parms” on page 97.
ECI_NO_ERROR
The call completed successfully.
ECI_ERR_INVALID_DATA_LENGTH
The value in eci_commarea_length field is outside the valid range, or
is inconsistent with the value in eci_commarea, being zero for a
non-null eci_commarea pointer, or non-zero for a null eci_commarea
pointer.
ECI_ERR_INVALID_EXTEND_MODE
The value in eci_extend_mode field is not valid.
ECI_ERR_NO_CICS
The CICS Transaction Gateway is unavailable, or the server
implementation is unavailable, or a logical unit of work was to be
begun, but the CICS server specified in eci_system_name is not
available. No resources have been updated.
ECI_ERR_CICS_DIED
A logical unit of work was to be begun or continued, but the CICS
server was no longer available. If eci_extend_mode was
ECI_EXTENDED, the changes are backed out, and the logical unit of
work ends. If eci_extend_mode was ECI_NO_EXTEND,
ECI_COMMIT, or ECI_BACKOUT, the application cannot determine
whether the changes have been committed or backed out, and must
log this condition to aid future manual recovery.
ECI_ERR_TRANSACTION_ABEND
The CICS transaction that executed the requested program abended.
The abend code will be found in eci_abend_code. For information
about abend codes and their meaning, consult the documentation for
the server system to which the request was directed.
ECI_ERR_LUW_TOKEN
The value supplied in eci_luw_token is invalid.
Chapter 4. C and COBOL 105

ECI_ERR_ALREADY_ACTIVE
An attempt was made to continue an existing logical unit of work, but
there was an outstanding asynchronous call for the same logical unit
of work.
ECI_ERR_RESOURCE_SHORTAGE
The server implementation or the Client daemon did not have enough
resources to complete the request.
ECI_ERR_NO_SESSIONS
A new logical unit of work was being created, but the application
already has as many outstanding logical units of work as the
configuration will support.
ECI_ERR_INVALID_DATA_AREA
Either the pointer to the ECI parameter block is invalid, or the pointer
supplied in eci_commarea is invalid.
ECI_ERR_ROLLEDBACK
An attempt was made to commit a logical unit of work, but the server
was unable to commit the changes, and backed them out instead.
ECI_ERR_UNKNOWN_SERVER
The requested server could not be located. Only servers returned by
CICS_EciListSystems are acceptable.
ECI_ERR_MAX_SESSIONS
There were not enough communication resources to satisfy the
request. Consult the documentation for your CICS Transaction
Gateway or server to see how to control communication resources.
ECI_ERR_MAX_SYSTEMS
You tried to start requests to more servers than your configuration
allows. Consult the documentation for your CICS Transaction
Gateway or server to see how to control the number of servers you
can use.
ECI_ERR_SECURITY_ERROR
You did not supply a valid combination of user ID and password.
ECI_ASYNC call type
Environment:
Purpose: The ECI_ASYNC call type provides an asynchronous program link
call to start, continue, or end a logical unit of work. The calling application
gets control back when the ECI has accepted the request. At this point the
parameters have been validated; however, the request might still be queued
for later processing.
106 CICS Transaction Gateway: Programming Reference

If no callback routine is provided, the application must use a reply solicitation
call to determine whether the request has ended and what the outcome was.
If a callback routine is provided, the callback routine eci_callback is invoked
when a response is available.
Note: Some compilers do not support the use of callback routines. Consult
your compiler documentation for more information.
It is important that the Eci parameter blocks of outstanding
ECI_ASYNC calls are not modified before the results of the call are
received. Results will be incorrect if these blocks are modified before
this stage.
When the callback routine is called, it is passed a single parameter—the value
specified in eci_message_qualifier. This enables the callback routine to
identify the asynchronous call that is completing. Follow these guidelines
when using the callback routine:
1. The minimum possible processing should be performed within the
callback routine.
2. ECI functions cannot be invoked from within the callback routine.
3. The callback routine should indicate to the main body of the application
that the reply is available using an appropriate technique for the operating
system upon which the ECI application is executing. For example, in a
multithreaded environment, the callback routine might post a semaphore
to signal another thread that an event has occurred.
4. The application, not the callback routine, must use a reply solicitation call
to receive the actual response.
ECI parameter block fields: Set the ECI parameter block to nulls before you
set the input parameter fields.
eci_call_type
Required input parameter.
Must be set to ECI_ASYNC.
eci_program_name
Input only, required parameter except when eci_extend_mode is
ECI_COMMIT or ECI_BACKOUT. (See the Logical units of work in ECI
table in CICS Transaction Gateway: Programming Guide for more details.)
An 8-character field containing the name of the program to be called.
Pad unused characters with spaces. This field is transmitted to the
server without conversion to uppercase.
The characters used are translated from the client’s code page to an
EBCDIC code page before transmission. If the server uses an ASCII
Chapter 4. C and COBOL 107

code page, they will be retranslated. The only characters guaranteed
to be invariant under these translations are the uppercase characters A
to Z, and the numeric characters 0 to 9. Some EBCDIC servers
(Katakana and Hebrew character set A) do not use the standard
representations of the lowercase alphabetic characters; use them with
care when communicating with such servers.
eci_userid
Required input parameter.
An 8-character field containing a user ID. Pad unused characters with
spaces.
Consult the documentation for the CICS Transaction Gateway and the
server to check whether this field is converted to upper case before
being transmitted to the server. (If a user ID or password longer than
8 characters is required, set eci_userid and eci_password to nulls, and
use eci_userid2 and eci_password2 instead.)
If a user ID is supplied, the server uses the user ID and any supplied
password to authenticate the user. The supplied user ID and
password are used in subsequent security checking in the server.
eci_password
Required input parameter.
An 8-character field containing a password. Pad unused characters
with spaces.
Consult the documentation for the CICS Transaction Gateway and the
server to check whether this field is converted to upper case before
being transmitted to the server. (If a user ID or password longer than
8 characters is required, set eci_userid and eci_password to nulls, and
use eci_userid2 and eci_password2 instead.)
eci_transid
Optional input parameter
A 4-character field optionally containing the ID of a CICS transaction.
Pad unused characters with spaces. The parameter is ignored if
eci_tpn is used (set to any value other than nulls). The use of this
parameter depends on the client from which the request is sent. The
value of eci_transid is converted from ASCII to EBCDIC, with no
upper case translation, and stored in EIBTRNID for the duration of
the LINK to the program specified in the eci_program_name.
The called program runs under the mirror transaction CPMI, but is
linked to under the eci_transid transaction name. This name is
available to the called program for querying the transaction ID. Some
servers use the transaction ID to determine security and performance
108 CICS Transaction Gateway: Programming Reference

attributes for the called program. In those servers, you are
recommended to use this parameter to control the processing of your
called programs.
If the ECI request is extended (see “eci_extend_mode”), the
eci_transid parameter has a meaning only for the first call in the unit
of work.
If the field is all nulls, and eci_tpn is not specified, the default server
transaction ID is used.
eci_commarea
Required input parameter.
A pointer to the data to be passed to the called CICS program as its
COMMAREA.
If no COMMAREA is required, supply a null pointer and set the
length (specified in eci_commarea_length) to zero.
If the code page of the application is different from the code page of
the server, data conversion must be performed at the server. To do
this, use CICS-supplied resource conversion capabilities, such as the
DFHCNV macro definitions.
eci_commarea_length
Required input parameter.
The length of the COMMAREA in bytes. This value may not exceed
32 500. (Some client/server combinations may allow larger
COMMAREAs, but this is not guaranteed to work.)
If no COMMAREA is required, set this field to zero and supply a null
pointer in eci_commarea.
eci_timeout
The time in seconds to wait for a response from the CICS server. A
value of 0 means that no limit is set.
If timeout occurs, the conversation is abended.
reserved1
Output parameter.
This field was previously eci_system_ return_code. In the CICS
Transaction Gateway Version 3.1, and higher, this field is reserved for
backward compatibility. No information is returned in this field; all
system errors are written to the error log.
eci_extend_mode
Required input parameter.
Chapter 4. C and COBOL 109

An integer field determining whether a logical unit of work is
terminated at the end of this call. (See the Logical units of work in ECI
table in CICS Transaction Gateway: Programming Guide for more details.)
Values (shown by their symbolic names) for this field are as follows:
ECI_NO_EXTEND
1. If the input eci_luw_token field is zero, this is the only
call for a logical unit of work.
2. If the input eci_luw_token field is not zero, this is the last
call for the specified logical unit of work.
In either case, changes to recoverable resources are committed
by a CICS end-of-task syncpoint, and the logical unit of work
ends.
ECI_EXTENDED
1. If the input eci_luw_token field is zero, this is the first call
for a logical unit of work that is to be continued.
2. If the input eci_luw_token field is not zero, this call is
intended to continue the specified logical unit of work.
In either case the logical unit of work continues after the
called program completes, and changes to recoverable
resources remain uncommitted.
ECI_COMMIT
Terminate the current logical unit of work, identified by the
input eci_luw_token field, and commit all changes made to
recoverable resources.
ECI_BACKOUT
Terminate the logical unit of work identified by the input
eci_luw_token field, and back out all changes made to
recoverable resources.
eci_message_qualifier
Optional input parameter.
An integer field allowing the application to identify each
asynchronous call if it is making more than one. If a callback routine
is specified, the value in this field is returned to the callback routine
during the notification process.
eci_luw_token
Required input and output parameter.
An integer field used for identifying the logical unit of work to which
a call belongs. It must be set to zero at the start of a logical unit of
work (regardless of whether the logical unit of work is going to be
110 CICS Transaction Gateway: Programming Reference

extended), and the ECI updates it with a valid value on the first or
only call of the logical unit of work. If the logical unit of work is to be
extended, this value should be used as input to all later calls related
to the same logical unit of work. (See the Logical units of work in ECI
table in CICS Transaction Gateway: Programming Guide for more details.)
If the return code is not ECI_NO_ERROR, and the call was continuing
or ending an existing logical unit of work, this field is used as output
to report the condition of the logical unit of work. If it is set to zero,
the logical unit of work has ended, and its updates have been backed
out. If it is nonzero, it is the same as the input value, the logical unit
of work is continuing, and its updates are still pending.
eci_sysid
Required input parameter.
Reserved for future use, but this field should be initialized with nulls
before the start of each logical unit of work.
eci_version
Required input parameter.
The version of the ECI for which the application is coded. You may
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the
facilities of version 1 are available in version 1A. Facilities available
only in version 1A are noted where they occur.
eci_system_name
Optional input parameter.
An 8-character field that specifies the name of the server to which the
ECI request is to be directed. Pad unused characters with spaces. The
value may be supplied whenever eci_luw_token is set to zero. (If it is
supplied when eci_luw_token is not zero, it is ignored, because the
server was established at the start of the logical unit of work.)
If the field is set to nulls, the default server is selected.You can obtain
the name of the chosen server from the eci_system_name field of the
reply solicitation call you use to get the result of this asynchronous
request. (If later ECI requests made in different logical units of work
must be directed to the same server as this request, eci_system_name
in those requests must identify that server by name.)
eci_callback
Optional input parameter.
A pointer to the routine to be called when the asynchronous request
completes. (The callback routine will be called only if the return code
is ECI_NO_ERROR, and the pointer is not null.)
Chapter 4. C and COBOL 111

eci_userid2
Optional input parameter.
If the eci_userid field is set to nulls, the eci_userid2 field specifies the
user ID (if any) to be used at the server for any authority validation.
The user ID can be up to 16 characters.
See the description of the eci_userid field for information about how
the user ID is used.
eci_password2
Optional input parameter.
If the eci_password field is set to nulls, the eci_password2 field
specifies the password (if any) to be used at the server for any
authority validation. The password can be up to 16 characters.
See the description of the eci_password field for information about
how the password is used.
eci_tpn
Optional input parameter. Available only if the value of eci_version is
ECI_VERSION_1A.
A 4-character field that specifies the transaction ID of the transaction
that will be used in the server to process the ECI request. This
transaction must be defined in the server as a CICS mirror transaction.
If the field is not set, the default mirror transaction CPMI is used.
If the ECI request is extended (see the description of
eci_extend_mode), this parameter has a meaning only for the first
request.
If this field is used, the contents of eci_transid are ignored.
Return codes: See also the general list of return codes for CICS_ExternalCall
in “CICS_ExternalCall ECI_Parms” on page 97.
If the return code is not ECI_NO_ERROR, the callback routine will not be
called, and there will be no asynchronous reply for this request.
ECI_NO_ERROR
The call to the ECI completed successfully. No errors have yet been
detected. The callback routine will be called when the request
completes.
ECI_ERR_INVALID_DATA_LENGTH
The value in eci_commarea_length field is outside the valid range, or
is inconsistent with the value in eci_commarea, being zero for a
non-null eci_commarea pointer, or non-zero for a null eci_commarea
pointer.
112 CICS Transaction Gateway: Programming Reference

ECI_ERR_INVALID_EXTEND_MODE
The value in eci_extend_mode field is not valid.
ECI_ERR_NO_CICS
Either the client or the server implementation is not available.
ECI_ERR_LUW_TOKEN
The value supplied in eci_luw_token is invalid.
ECI_ERR_THREAD_CREATE_ERROR
The server implementation or the client failed to create a thread to
process the request.
ECI_ERR_ALREADY_ACTIVE
An attempt was made to continue an existing logical unit of work, but
there was an outstanding asynchronous call for the same logical unit
of work.
ECI_ERR_RESOURCE_SHORTAGE
The server implementation or the client did not have enough
resources to complete the request.
ECI_ERR_NO_SESSIONS
A new logical unit of work was being created, but the application
already has as many outstanding logical units of work as the
configuration will support.
ECI_ERR_INVALID_DATA_AREA
Either the pointer to the ECI parameter block is invalid, or the pointer
supplied in eci_commarea is invalid.
ECI_STATE_SYNC call type
Environment: The ECI_STATE_SYNC call type is available in all
environments.
Purpose: The ECI_STATE_SYNC call type provides a synchronous status
information call.
ECI parameter block fields: The ECI parameter block should be set to nulls
before setting the input parameter fields.
eci_call_type
Required input parameter.
Must be set to ECI_STATE_SYNC.
eci_commarea
Input parameter, required except when eci_extend_mode has the
value ECI_STATE_CANCEL.
Chapter 4. C and COBOL 113

A pointer to the area of storage where the application receives the
returned COMMAREA containing status information. See Status
information calls, intheExternal call interface chapter, in CICS
Transaction Gateway: Programming Guide, and “ECI status block” on
page 128, for more details.
If eci_extend_mode has the value ECI_STATE_CANCEL, supply a
null pointer and set the length (specified in eci_commarea_length) to
zero.
eci_commarea_length
Required input and output parameter, except when eci_extend_mode
has the value ECI_STATE_CANCEL.
The length of the COMMAREA in bytes, which must be the length of
the ECI_STATUS structure that gives the layout of the status
information COMMAREA. See Status information calls, intheExternal
call interface chapter, in CICS Transaction Gateway: Programming Guide,
and “ECI status block” on page 128, for more details. Area size must
not exceed 32 500 bytes
If no COMMAREA is required, set this field to zero and supply a null
pointer in eci_commarea.
reserved1
Output parameter.
This field was previously eci_system_ return_code. In the CICS
Transaction Gateway Version 3.1, and higher, this field is reserved for
backward compatibility. No information is returned in this field; all
system errors are written to the error log.
eci_extend_mode
Required input parameter.
An integer field further qualifying the call type. The values for this
field (shown by their symbolic names) are as follows:
ECI_STATE_IMMEDIATE
Force a status reply to be sent immediately it is available. The
layout of the returned COMMAREA is defined in the
ECI_STATUS structure. See Status information calls, inthe
External call interface chapter, in CICS Transaction Gateway:
Programming Guide, and “ECI status block” on page 128, for
more details.
ECI_STATE_CHANGED
Force a status reply to be sent only when the status changes.
The supplied COMMAREA must contain the status as
perceived by the application. A reply is sent only when there
is a change from the status that the application supplied. The
114 CICS Transaction Gateway: Programming Reference

layout of the COMMAREA is defined in the ECI_STATUS
structure. See Status information calls, intheExternal call
interface chapter, in CICS Transaction Gateway: Programming
Guide, and “ECI status block” on page 128, for more details.
The eci_luw_token field that is returned on the immediate
response provides a token to identify the request.
ECI_STATE_CANCEL
Cancel an ECI_STATE_CHANGED type of operation. No
COMMAREA is required for this request. The eci_luw_token
field must contain the token that was received during the
ECI_STATE_CHANGED call.
eci_luw_token
Optional input and output parameter.
When a deferred status request is being set up (eci_extend_mode set
to ECI_STATE_CHANGED), the token identifying the request is
returned in the eci_luw_token field.
When a deferred status request is being cancelled (eci_extend_mode
set to ECI_STATE_CANCEL), the eci_luw_token field must contain
the token that was received during the ECI_STATE_CHANGED call.
This field is not used when other values of eci_extend_mode are
specified.
eci_sysid
Required input parameter.
Reserved for future use, but this field should be initialized with nulls
before the start of each logical unit of work.
eci_version
Required input parameter.
The version of the ECI for which the application is coded. You may
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the
facilities of version 1 are available in version 1A. Facilities available
only in version 1A are noted where they occur.
eci_system_name
Optional input parameter.
An 8-character field that specifies the name of the server for which
status information is required. Pad unused characters with spaces. If
supplied, it should be one of the server names returned by
CICS_EciListSystems. The value may be supplied whenever
eci_luw_token is set to zero.
If the field is set to nulls, the default server is selected; the name of
the chosen server is returned in this field.
Chapter 4. C and COBOL 115

Return codes: See also the general list of return codes for CICS_ExternalCall
in “CICS_ExternalCall ECI_Parms” on page 97.
ECI_NO_ERROR
The call completed successfully.
ECI_ERR_INVALID_DATA_LENGTH
The value in eci_commarea_length field is outside the valid range, or
is inconsistent with the value in eci_commarea, being zero for a
non-null eci_commarea pointer, or non-zero for a null eci_commarea
pointer.
ECI_ERR_INVALID_EXTEND_MODE
The value in eci_extend_mode field is not valid.
ECI_ERR_LUW_TOKEN
The value supplied in eci_luw_token is invalid.
ECI_ERR_INVALID_DATA_AREA
Either the pointer to the ECI parameter block is invalid, or the pointer
supplied in eci_commarea is invalid.
ECI_ERR_UNKNOWN_SERVER
The requested server could not be located. Only servers returned by
CICS_EciListSystems are acceptable.
ECI_STATE_ASYNC call type
Environment:
Purpose: The ECI_STATE_ASYNC call type provides an asynchronous status
information call. The calling application gets control back when the ECI
accepts the request. At this point the parameters have been validated;
however, the request might still be queued for later processing.
If no callback routine is provided, the application must use a reply solicitation
call to determine that the request has ended and what the outcome was.
If a callback routine is provided, the callback routine eci_callback is invoked
when a response is available.
Note: Some compilers do not support the use of callback routines. Consult
your compiler documentation for more information.
Note: It is important that the Eci parameter blocks of outstanding
ECI_STATE_ASYNC calls are not modified before the results of the call
are received. Results will be incorrect if these blocks are modified
before this stage.
116 CICS Transaction Gateway: Programming Reference

When the callback routine is called, it is passed a single parameter—the value
specified in eci_message_qualifier. This enables the callback routine to
identify the asynchronous call that is completing. Note the following
guidelines on the use of the callback routine:
1. The minimum possible processing should be performed within the
callback routine.
2. ECI functions cannot be invoked from within the callback routine.
3. The callback routine should indicate to the main body of the application
that the reply is available using an appropriate technique for the operating
system upon which the ECI application is executing. For example, in a
multithreaded environment, the callback routine might post a semaphore
to signal another thread that an event has occurred.
4. The application, not the callback routine, must use a reply solicitation call
to receive the actual response.
ECI parameter block fields: The ECI parameter block should be set to nulls
before setting the input parameter fields.
eci_call_type
Required input parameter.
Must be set to ECI_STATE_ASYNC.
eci_commarea
Input parameter, required except when eci_extend_mode has the
value ECI_STATE_CANCEL.
A pointer to the area of storage where the application receives the
returned COMMAREA containing status information. See Status
information calls, intheExternal call interface chapter, in CICS
Transaction Gateway: Programming Guide, and “ECI status block” on
page 128, for more details.
If eci_extend_mode has the value ECI_STATE_CANCEL, supply a
null pointer and set the length (specified in eci_commarea_length) to
zero.
eci_commarea_length
Required input parameter, except when eci_extend_mode has the
value ECI_STATE_CANCEL.
The length of the COMMAREA in bytes, which must be the length of
the ECI_STATUS structure that gives the layout of the status
information COMMAREA. See Status information calls, intheExternal
call interface chapter, in CICS Transaction Gateway: Programming Guide,
and “ECI status block” on page 128, for more details. Area size must
not exceed 32 500 bytes
Chapter 4. C and COBOL 117

If no COMMAREA is required, set this field to zero and supply a null
pointer in eci_commarea.
reserved1
Output parameter.
This field was previously eci_system_ return_code. In the CICS
Transaction Gateway Version 3.1, and higher, this field is reserved for
backward compatibility. No information is returned in this field; all
system errors are written to the error log.
eci_extend_mode
Required input parameter.
An integer field further qualifying the call type. The values for this
field (shown by their symbolic names) are as follows:
ECI_STATE_IMMEDIATE
Force a status reply to be sent immediately it is available. The
layout of the returned COMMAREA is defined in the
ECI_STATUS structure. See Status information calls, inthe
External call interface chapter, in CICS Transaction Gateway:
Programming Guide, and “ECI status block” on page 128, for
more details.
ECI_STATE_CHANGED
Force a status reply to be sent only when the status changes.
The supplied COMMAREA must contain the status as
perceived by the application. A reply is sent only when there
is a change from the status that the application supplied. The
layout of the COMMAREA is defined in the ECI_STATUS
structure. See Status information calls, intheExternal call
interface chapter, in CICS Transaction Gateway: Programming
Guide, and “ECI status block” on page 128, for more details.
The eci_luw_token field that is returned on the immediate
response identifies the logical unit of work to which this call
belongs.
ECI_STATE_CANCEL
Cancel an ECI_STATE_CHANGED type of operation. No
COMMAREA is required for this request. The eci_luw_token
field must contain the token that was received during the
ECI_STATE_CHANGED call.
eci_message_qualifier
Optional input parameter.
118 CICS Transaction Gateway: Programming Reference

An integer field allowing you to identify each asynchronous call if
you are making more than one. If a callback routine is specified, the
value in this field is returned to the callback routine during the
notification process.
eci_luw_token
Optional input and output parameter.
When a deferred status request is being set up (eci_extend_mode set
to ECI_STATE_CHANGED), the token identifying the request is
returned in the eci_luw_token field.
When a deferred status request is being cancelled (eci_extend_mode
set to ECI_STATE_CANCEL), the eci_luw_token field must contain
the token that was received during the ECI_STATE_CHANGED call.
This field is not used when other values of eci_extend_mode are
specified.
eci_sysid
Required input parameter.
Reserved for future use, but this field should be initialized with nulls
before the start of each logical unit of work.
eci_version
Required input parameter.
The version of the ECI for which the application is coded. You may
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the
facilities of version 1 are available in version 1A. Facilities available
only in version 1A are noted where they occur.
eci_system_name
Optional input parameter.
An 8-character field that specifies the name of the server for which
status information is requested. Pad unused characters with spaces. If
supplied, it should be one of the server names returned by
CICS_EciListSystems. The value may be supplied whenever
eci_luw_token is set to zero.
If the field is set to nulls, the default server is selected.You can find
out the name of the server from the eci_system_name field of the
reply solicitation call you use to get the result of this asynchronous
request. field.
eci_callback
Optional input parameter.
Chapter 4. C and COBOL 119

A pointer to the routine to be called when the asynchronous request
completes. (The callback routine will be called only if the return code
is ECI_NO_ERROR, and the pointer is not null.)
Return codes: See also the general list of return codes for CICS_ExternalCall
in “CICS_ExternalCall ECI_Parms” on page 97.
If the return code is not ECI_NO_ERROR, the callback routine will not be
called, and there will be no asynchronous reply for this request.
ECI_NO_ERROR
The call completed successfully.
ECI_ERR_INVALID_DATA_LENGTH
The value in eci_commarea_length field is outside the valid range, or
is inconsistent with the value in eci_commarea, being zero for a
non-null eci_commarea pointer, or non-zero for a null eci_commarea
pointer.
ECI_ERR_INVALID_EXTEND_MODE
The value in eci_extend_mode field is not valid.
ECI_ERR_LUW_TOKEN
The value supplied in eci_luw_token is invalid.
ECI_ERR_INVALID_DATA_AREA
Either the pointer to the ECI parameter block is invalid, or the pointer
supplied in eci_commarea is invalid.
ECI_GET_REPLY call type
Environment:
Purpose: The ECI_GET_REPLY call type provides a reply solicitation call to
return information appropriate to any outstanding reply for any asynchronous
request. If there is no such reply, ECI_ERR_NO_REPLY is returned. (To cause
the application to wait until a reply is available, use call type
ECI_GET_REPLY_WAIT instead.)
Note: It is important that the Eci parameter blocks of outstanding
ECI_ASYNC calls are not modified before the results of the call are
received (for example using this get reply call). Results will be incorrect
if these blocks are modified before this stage.
ECI parameter block fields: The ECI parameter block should be set to nulls
before setting the input parameter fields.
The following fields are the fields of the ECI parameter block that might be
supplied as input.
120 CICS Transaction Gateway: Programming Reference

In the course of an ECI_GET_REPLY call, the ECI parameter block is updated
as follows:
1. All the outputs from the reply, some of which overwrite input fields, are
added. These fields are those that are output from the corresponding
synchronous version of the asynchronous request.
2. The eci_message_qualifier value supplied as input to the asynchronous
request to which this reply relates is restored.
3. Any inputs that are not updated become undefined, except the pointer to
the COMMAREA. Do not use the contents of these fields again.
eci_call_type
Required input parameter.
Must be set to ECI_GET_REPLY.
eci_commarea
Optional input parameter.
A pointer to the area of storage where the application receives the
returned COMMAREA. The contents of the returned commarea
depend on the type of asynchronous call to which a reply is being
sought. For a program link call, it is the COMMAREA expected to be
returned from the called program, if any. For a status information call,
except when eci_extend_mode has the value ECI_STATE_CANCEL, it
is a COMMAREA containing status information. See Status information
calls, intheExternal call interface chapter, in CICS Transaction Gateway:
Programming Guide, and “ECI status block” on page 128, for more
details.
If no COMMAREA is required, supply a null pointer and set the
length (specified in eci_commarea_length) to zero.
If the code page of the application is different from the code page of
the server, data conversion must be performed at the server. To do
this, use CICS-supplied resource conversion capabilities, such as the
DFHCNV macro definitions.
eci_commarea_length
Required input parameter.
The length of the COMMAREA in bytes. This value may not exceed
32 500. (Some client/server combinations may allow larger
COMMAREAs, but this is not guaranteed to work.)
If no COMMAREA is required, set this field to zero and supply a null
pointer in eci_commarea.
eci_sysid
Required input parameter.
Chapter 4. C and COBOL 121

Reserved for future use, but this field should be initialized with nulls
before the start of each logical unit of work.
eci_version
Required input parameter.
The version of the ECI for which the application is coded. You may
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the
facilities of version 1 are available in version 1A. Facilities available
only in version 1A are noted where they occur.
Return codes: See also the general list of return codes for CICS_ExternalCall
in “CICS_ExternalCall ECI_Parms” on page 97.
ECI_NO_ERROR
The asynchronous request to which this reply relates completed
successfully.
ECI_ERR_INVALID_DATA_LENGTH
The value in eci_commarea_length field is unacceptable for one of the
following reasons:
v It is outside the valid range.
v It is inconsistent with the value in eci_commarea, being zero for a
non-null eci_commarea pointer, or non-zero for a null
eci_commarea pointer.
v It is not large enough for the output COMMAREA from the
asynchronous request to which this reply relates.
In the last case, you can use the output eci_commarea_length to
allocate more storage for the COMMAREA, and then use the output
eci_message_qualifier (if it identifies the asynchronous request
uniquely) with an ECI_GET_SPECIFIC_REPLY call type to retrieve the
reply.
ECI_ERR_NO_CICS
The CICS server specified in eci_system_name in the asynchronous
request to which this reply relates is not available. No resources have
been updated.
ECI_ERR_CICS_DIED
A logical unit of work was to be begun or continued by the
asynchronous request to which this reply relates, but the CICS server
was no longer available. If eci_extend_mode was ECI_EXTENDED,
the changes are backed out, and the logical unit of work ends. If
eci_extend_mode was ECI_NO_EXTEND, ECI_COMMIT, or
ECI_BACKOUT, the application cannot determine whether the
changes have been committed or backed out, and must log this
condition to aid future manual recovery.
122 CICS Transaction Gateway: Programming Reference

ECI_ERR_NO_REPLY
There was no outstanding reply.
ECI_ERR_TRANSACTION_ABEND
The asynchronous request to which this reply relates caused a
program to be executed in the server, but the CICS transaction that
executed the requested program abended. The abend code will be
found in eci_abend_code. For information about abend codes and
their meaning, consult the documentation for the server system to
which the request was directed.
ECI_ERR_THREAD_CREATE_ERROR
The CICS server or CICS Transaction Gateway failed to create the
thread to process the asynchronous call to which this reply relates.
ECI_ERR_RESOURCE_SHORTAGE
The server implementation or CICS Transaction Gateway did not have
enough resources to complete the asynchronous request to which this
reply relates.
ECI_ERR_INVALID_DATA_AREA
Either the pointer to the ECI parameter block is invalid, or the pointer
supplied in eci_commarea is invalid.
ECI_ERR_ROLLEDBACK
The asynchronous request to which this reply relates attempted to
commit a logical unit of work, but the server was unable to commit
the changes, and backed them out instead.
ECI_ERR_UNKNOWN_SERVER
The asynchronous request to which this reply relates specified a
server that could not be located. Only servers returned by
CICS_EciListSystems are acceptable.
ECI_ERR_MAX_SESSIONS
There were not enough communication resources to satisfy the
asynchronous request to which this reply relates. Consult the
documentation for your CICS Transaction Gateway or server to see
how to control communication resources.
ECI_ERR_MAX_SYSTEMS
The asynchronous request to which this reply relates attempted to
start requests to more servers than your configuration allows. Consult
the documentation for your CICS Transaction Gateway or server to
see how to control the number of servers you can use.
ECI_ERR_SECURITY_ERROR
You did not supply a valid combination of userid and password on
the asynchronous request to which this reply relates.
Chapter 4. C and COBOL 123

ECI_GET_REPLY_WAIT call type
Environment:
Purpose: The ECI_GET_REPLY_WAIT call type provides a reply solicitation
call to return information appropriate to any outstanding reply for any
asynchronous request. If there is no such reply, the application waits until
there is. (You can get an indication that no reply is available by using call type
ECI_GET_REPLY instead.)
Note: It is important that the Eci parameter blocks of outstanding
ECI_STATE_ASYNC calls are not modified before the results of the call
are received. Results will be incorrect if these blocks are modified
before this stage.
ECI parameter block fields: Same as for ECI_GET_REPLY, but eci_call_type
must be set to ECI_GET_REPLY_WAIT.
Return codes: Same as for ECI_GET_REPLY, except that
ECI_ERR_NO_REPLY cannot be returned.
ECI_GET_SPECIFIC_REPLY call type
Purpose: The ECI_GET_SPECIFIC_REPLY call type provides a reply
solicitation call to return information appropriate to any outstanding reply
that matches the eci_message_qualifier input. If there is no such reply,
ECI_ERR_NO_REPLY is returned. (To cause the application to wait until a
reply is available, use call type ECI_GET_REPLY_WAIT instead.)
Note: It is important that the Eci parameter blocks of outstanding
ECI_STATE_ASYNC calls are not modified before the results of the call
are received. Results will be incorrect if these blocks are modified
before this stage.
ECI parameter block fields: Set the ECI parameter block to nulls before
setting the input parameter fields.
The following fields are the fields of the ECI parameter block that might be
supplied as input.
In the course of an ECI_GET_REPLY call, the ECI parameter block is updated
as follows:
1. All the outputs from the reply, some of which overwrite input fields, are
added. These fields are those that are output from the corresponding
synchronous version of the asynchronous request.
124 CICS Transaction Gateway: Programming Reference

2. Any inputs that are not updated become undefined, except the pointer to
the COMMAREA and the input eci_message_qualifier. Do not use the
contents of these fields again.
eci_call_type
Required input parameter.
Must be set to ECI_GET_SPECIFIC_REPLY.
eci_commarea
Optional input parameter.
A pointer to the area of storage where the application receives the
returned COMMAREA. The contents of the returned commarea
depend on the type of asynchronous call to which a reply is being
sought. For a program link call, it is the COMMAREA expected to be
returned from the called program, if any. For a status information call,
except one in which eci_extend_mode had the value
ECI_STATE_CANCEL, it is a COMMAREA containing status
information. See Status information calls, intheExternal call interface
chapter, in CICS Transaction Gateway: Programming Guide, and “ECI
status block” on page 128, for more details.
If the code page of the application is different from the code page of
the server, data conversion must be performed at the server. To do
this, use CICS-supplied resource conversion capabilities, such as the
DFHCNV macro definitions.
eci_commarea_length
Required input parameter.
The length of the COMMAREA in bytes. This value may not exceed
32 500. (Some client/server combinations may allow larger
COMMAREAs, but this is not guaranteed to work.)
eci_message_qualifier
Required input parameter.
An integer field that identifies the asynchronous call for which a reply
is being solicited.
eci_sysid
Required input parameter.
Reserved for future use, but this field should be initialized with nulls
before the start of each logical unit of work.
eci_version
Required input parameter.
The version of the ECI for which the application is coded. You may
use the values ECI_VERSION_1 or ECI_VERSION_1A. All the
Chapter 4. C and COBOL 125

facilities of version 1 are available in version 1A. Facilities available
only in version 1A are noted where they occur.
Return codes: See also the general list of return codes for CICS_ExternalCall
in “CICS_ExternalCall ECI_Parms” on page 97.
ECI_NO_ERROR
The call completed successfully.
ECI_ERR_INVALID_DATA_LENGTH
The value in eci_commarea_length field is unacceptable for one of the
following reasons:
v It is outside the valid range.
v It is inconsistent with the value in eci_commarea, being zero for a
non-null eci_commarea pointer, or non-zero for a null
eci_commarea pointer.
v It is not large enough for the output COMMAREA from the
asynchronous request to which this reply relates.
In the last case, you can use the output eci_commarea_length to
allocate more storage for the COMMAREA, and then retry the
ECI_GET_SPECIFIC_REPLY call.
ECI_ERR_NO_CICS
The CICS server specified in eci_system_name in the asynchronous
request to which this reply relates is not available. No resources have
been updated.
ECI_ERR_CICS_DIED
A logical unit of work was to be begun or continued by the
asynchronous request to which this reply relates, but the CICS server
was no longer available. If eci_extend_mode was ECI_EXTENDED,
the changes are backed out, and the logical unit of work ends. If
eci_extend_mode was ECI_NO_EXTEND, ECI_COMMIT, or
ECI_BACKOUT, the application cannot determine whether the
changes have been committed or backed out, and must log this
condition to aid future manual recovery.
ECI_ERR_NO_REPLY
There was no outstanding reply that matched the input
eci_message_qualifier.
ECI_ERR_TRANSACTION_ABEND
The asynchronous request to which this reply relates caused a
program to be executed in the server, but the CICS transaction that
executed the requested program abended. The abend code will be
found in eci_abend_code. For information about abend codes and
their meaning, consult the documentation for the server system to
which the request was directed.
126 CICS Transaction Gateway: Programming Reference

ECI_ERR_THREAD_CREATE_ERROR
The CICS server or CICS Transaction Gateway failed to create the
thread to process the asynchronous request to which this reply relates.
ECI_ERR_RESOURCE_SHORTAGE
The CICS server or CICS Transaction Gateway did not have enough
resources to complete the asynchronous request to which this reply
relates.
ECI_ERR_INVALID_DATA_AREA
Either the pointer to the ECI parameter block is invalid, or the pointer
supplied in eci_commarea is invalid.
ECI_ERR_ROLLEDBACK
The asynchronous request to which this reply relates attempted to
commit a logical unit of work, but the server was unable to commit
the changes, and backed them out instead.
ECI_ERR_UNKNOWN_SERVER
The asynchronous request to which this reply relates specified a
server that could not be located. Only servers returned by
CICS_EciListSystems are acceptable.
ECI_ERR_MAX_SESSIONS
There were not enough communication resources to satisfy the
asynchronous request to which this reply relates. Consult the
documentation for your CICS Transaction Gateway or server to see
how to control communication resources.
ECI_ERR_MAX_SYSTEMS
The asynchronous request to which this reply relates attempted to
start requests to more servers than your configuration allows. Consult
the documentation for your CICS Transaction Gateway or server to
see how to control the number of servers you can use.
ECI_ERR_SECURITY_ERROR
You did not supply a valid combination of userid and password on
the asynchronous request to which this reply relates.
ECI_GET_SPECIFIC_REPLY_WAIT call type
Environment:
Purpose: The ECI_GET_SPECIFIC_REPLY_WAIT call type provides a reply
solicitation call to return information appropriate to any outstanding reply
that matches the input eci_message_qualifier. If there is no such reply, the
application waits until there is. (You can get an indication that no reply is
available by using call type ECI_GET_SPECIFIC_REPLY instead.)
Chapter 4. C and COBOL 127

Note: It is important that the Eci parameter blocks of outstanding
ECI_STATE_ASYNC calls are not modified before the results of the call
are received. Results will be incorrect if these blocks are modified
before this stage.
ECI parameter block fields: Same as for ECI_GET_SPECIFIC_REPLY, but
eci_call_type must be set to ECI_GET_SPECIFIC_REPLY_WAIT.
Return codes: Same as for ECI_GET_SPECIFIC_REPLY, except that
ECI_ERR_NO_REPLY cannot be returned.
Note: If you issue an ECI_GET_SPECIFIC_REPLY_WAIT call against an
outstanding ECI_STATE_AYSNC call with eci_extend mode set to
ECI_STATE_CHANGED, no response will ever be received if an
ECI_STATE_ASYNC call with eci_extend_mode set to
ECI_STATE_CANCEL is issued.
ECI status block
The ECI status block is used in status information calls to pass information to
and from the ECI. It contains the following fields:
ConnectionType
An integer field specifying the type of system on which the
application is running, with the following possible values:
ECI_CONNECTED_NOWHERE
Application is not connected to anything.
ECI_CONNECTED_TO_CLIENT
Application is running on a client system.
ECI_CONNECTED_TO_SERVER
Application is using a server implementation of the ECI.
CicsServerStatus
An integer field specifying the state of the CICS server, with the
following possible values:
ECI_SERVERSTATE_UNKNOWN
The CICS server state could not be determined.
ECI_SERVERSTATE_UP
The CICS server is available to run programs.
ECI_SERVERSTATE_DOWN
The CICS server is not available to run programs.
CicsClientStatus
An integer field specifying the state of the Client daemon, with the
following possible values:
128 CICS Transaction Gateway: Programming Reference

ECI_CLIENTSTATE_UNKNOWN
The Client daemon state could not be determined.
ECI_CLIENTSTATE_UP
The Client daemon is available to receive ECI calls.
ECI_CLIENTSTATE_INAPPLICABLE
The application is using a server implementation of the ECI.
CICS_EciListSystems NameSpace Systems List
ECI status block
Purpose
The CICS_EciListSystems function provides a list of CICS servers to which
CICS_ExternalCall requests may be directed. There is no guarantee that a
communications link exists between the Client daemon and any server in the
list, or that any of the servers is available to process requests.
The list of servers is returned as an array of system information structures,
one element for each CICS server. The structure, called CICS_EciSystem_t,
defines the following fields.
SystemName
A pointer to a null-terminated string specifying the name of a CICS
server. If the name is shorter than CICS_ECI_SYSTEM_MAX, it is
padded with nulls to a length of CICS_ECI_SYSTEM_MAX + 1.
Description
A pointer to a null-terminated string that provides a description of the
system, if one is available. If the description is shorter than
CICS_ECI_DESCRIPTION_MAX characters, it is padded with nulls to
a length of CICS_ECI_DESCRIPTION_MAX + 1.
Parameters
NameSpace
A pointer reserved for future use. Ensure that this is a null pointer.
Systems
On entry to the function, this parameter specifies the number of
elements in the array provided in the List parameter. On return it
contains the actual number of systems found.
List An array of CICS_EciSystem_t structures that are filled in and
returned by the function. The application must provide storage for the
array, and must set the Systems parameter to indicate the number of
elements in the array. The first name in the list is the default server.
However, the way in which the default is defined depends upon the
operating system.
Chapter 4. C and COBOL 129

ECI status block
Return Codes
ECI_NO_ERROR
The function completed successfully. The number of systems found is
at least one, and does not exceed the value supplied as input in the
Systems parameter.
ECI_ERR_MORE_SYSTEMS
There was not enough space in the List array to store the information.
The supplied array has been filled, and the Systems parameter has
been updated to contain the total number of systems found, so that
you can reallocate an array of suitable size and try the function again.
ECI_ERR_NO_SYSTEMS
No CICS servers can be located. In this case, the value returned in
Systems is zero.
ECI_ERR_NO_CICS
The Client daemon is not active.
ECI_ERR_INVALID_DATA _LENGTH
The value specified in the Systems parameter is so large that the
length of storage for the List parameter exceeds 32 767.
ECI_ERR_CALL_FROM_CALLBACK
The call was made from a callback routine.
ECI_ERR_SYSTEM_ERROR
An internal system error occurred.
External Presentation Interface
EPI constants and data structures
This section describes the constants and data structures that you will need to
use the EPI. They are referred to in “EPI functions” on page 137.
EPI constants
The following constants are referred to symbolically in the descriptions of the
EPI data structures, functions, and events in this Chapter. Their values are
given here to help you understand the descriptions. However, your code
should always use the symbolic names of EPI constants provided for the
programming language you are using.
Lengths of fields
v CICS_EPI_SYSTEM_MAX (8)
v CICS_EPI_DESCRIPTION_MAX (60)
v CICS_EPI_NETNAME_MAX (8)
v CICS_EPI_TRANSID_MAX (4)
v CICS_EPI_ABEND_MAX (4)
130 CICS Transaction Gateway: Programming Reference

v CICS_EPI_DEVTYPE_MAX (16)
v CICS_EPI_ERROR_MAX (60).
v CICS_EPI_PASSWORD_MAX (10)
v CICS_EPI_USERID_MAX (10)
v CICS_EPI_MAPNAME_MAX (7)
v CICS_EPI_MAPSETNAME_MAX (8)
v CICS_EPI_TERMID_MAX (4)
Relating to TermIndex
v CICS_EPI_TERM_INDEX_NONE 0xFFFF.
Version numbers (See EPI versions, inCICS Transaction Gateway: Programming
Guide.)
v CICS_EPI_VERSION_100
v CICS_EPI_VERSION_101.
v CICS_EPI_VERSION_200.
EPI data structures
The following data structures are available for use with the EPI.
v CICS_EpiSystem_t
v CICS_EpiAttributes_t
v CICS_EpiDetails_t
v CICS_EpiEventData_t
v CICS_EpiSysError_t.
In the descriptions of the fields in the data structures, fields described as
strings are null-terminated strings.
CICS_EpiSystem_t:
EPI constants and data structures
Purpose: The CICS_EpiSystem_t structure contains the name and description
of a CICS server. An array of these structures is returned from the
CICS_EpiListSystems function.
Fields:
SystemName
A string naming the CICS server. It can be passed as a parameter to
the CICS_EpiAddTerminal and CICS_EpiAddExTerminal functions,
to identify the CICS server in which the terminal resource should be
installed. If the name is shorter than CICS_EPI_SYSTEM_MAX
characters, it is padded with nulls to a length of
CICS_EPI_SYSTEM_MAX + 1.
Description
A string giving a brief description of the server. If the description is
shorter than CICS_EPI_DESCRIPTION_MAX, it is padded with nulls
to a length of CICS_EPI_DESCRIPTION_MAX + 1.
Chapter 4. C and COBOL 131

EPI constants and data structures
CICS_EpiAttributes_t:
Purpose: The CICS_EpiAttributes_t structure holds information about the
attributes to be associated with a terminal resource installed by the
CICS_EpiAddExTerminal function.
This data structure is supported only for CICS_EPI_VERSION_200.
Fields:
EpiAddType
Indicates whether the application is prepared to wait until the request
to install the terminal is complete. Use one of the following values:
CICS_EPI_ADD_ASYNC
The calling application gets control back when the request to
install the terminal resource has been accepted; at this point
the parameters have been validated.
Assuming valid parameters, the
CICS_EPI_EVENT_ADD_TERM event is generated when the
request to install the terminal has completed.
The TermIndex is returned for use with the
CICS_EpiGetEvent function.
CICS_EPI_ADD_SYNC
The calling application gets control back when the request to
install the terminal resource has completed. Returned
information is immediately available.
InstallTimeOut
A value in the range 0 through 3600, specifying the maximum time in
seconds that installation of the terminal resource is allowed to take; a
value of 0 means that no limit is set.
A value of 3600 is assumed if a larger value is specified.
ReadTimeOut
A value in the range 0 through 3600, specifying the maximum time in
seconds that is allowed between notification of a
CICS_EPI_EVENT_CONVERSE event for the terminal resource and
the following invocation of the CICS_EpiReply; a value of 0 means
that no limit is set.
A value of 3600 is assumed if a larger value is specified.
If time-out occurs, the conversation is abended. This results in a
CICS_EPI_EVENT_END_TRAN event being generated; the
EndReason field is set to CICS_EPI_READTIMEOUT_EXPIRED; the
AbendCode field is not set.
132 CICS Transaction Gateway: Programming Reference

SignonCapability
Indicates whether the application may start server-provided signon
and signoff transactions from the terminal resource. Use one of the
following values:
CICS_EPI_SIGNON_CAPABLE
The terminal resource is to be installed as signon capable.
CICS_EPI_SIGNON_INCAPABLE
The resource is to be installed as signon incapable.
CCSId
A value in the range 1 through 65536 specifying the coded character
set identifier (CCSID) that identifies the coded graphic character set
used by the client application for data passed between the terminal
resource and CICS transactions.
A value of 0 means that a default CCSID is used.
For details on the CCSID values for various character sets see Data
conversion when using the Client daemon, intheCICS Transaction
Gateway: Administration book for your operating system.
UserId
A string specifying the userid to be associated with the terminal
resource. If the userid is shorter than CICS_EPI_USERID_MAX, it
must be padded with nulls to a length of CICS_EPI_USERID_MAX+1.
Password
A string specifying the password to be associated with the terminal
resource. If the password is shorter than CICS_EPI_PASSWORD_MAX
characters, it must be padded with nulls to a length of
CICS_EPI_PASSWORD_MAX+1.
CICS_EpiDetails_t:
EPI constants and data structures
Purpose: The CICS_EpiDetails_t structure holds information about a terminal
resource installed by the CICS_EpiAddTerminal or the
CICS_EpiAddExTerminal function.
Fields:
NetName
A string specifying the VTAM ® -style netname of the terminal
resource. If the name is shorter than CICS_EPI_NETNAME_MAX
characters, it is padded with nulls to a length of
CICS_EPI_NETNAME_MAX + 1.
Chapter 4. C and COBOL 133

EPI constants and data structures
NumLines
The number of rows supported by the terminal resource.
NumColumns
The number of columns supported by the terminal resource.
MaxData
The maximum size of data that can be sent to this terminal resource
from a CICS transaction, and the maximum size of data that can be
sent from this terminal resource to a CICS transaction by a
CICS_EpiStartTran call or CICS_EpiReply call.
The maximum size may be defined in the model terminal definition
specified by the DevType parameter on the CICS_EpiAddTerminal
call that installed the terminal resource in the server. If the value
either is not specified in the model terminal definition, a default value
of 12000 is assumed.
ErrLastLine
1 if the terminal resource should display error messages on its last
row, 0 otherwise.
ErrIntensify
1 if the terminal resource should display error messages intensified, 0
otherwise.
ErrColor
The 3270 attribute defining the color to be used to display error
messages.
ErrHilight
The 3270 attribute defining the highlight value to be used to display
error messages.
Hilight
1 if the terminal resource is defined to support extended highlighting,
0 otherwise.
Color 1 if the terminal resource is defined to support color, 0 otherwise.
System
TermId
A string specifying the name of the server in which the terminal
resource has been installed. If the name is shorter than
CICS_EPI_SYSTEM_MAX characters, it is padded with nulls to a
length of CICS_EPI_SYSTEM_MAX + 1.
This field is supported only for CICS_EPI_VERSION_200.
A string specifying the name of the terminal resource. If the name is
shorter than CICS_EPI_TERMID_MAX characters, it is padded with
nulls to a length of CICS_EPI_TERMID_MAX + 1.
134 CICS Transaction Gateway: Programming Reference

This field is supported only for CICS_EPI_VERSION_200.
SignonCapability
The signon capability assigned by the server to the terminal resource:
CICS_EPI_SIGNON_CAPABLE
if the application may start server-provided signon and
signoff transactions at the terminal resource.
CICS_EPI_SIGNON_INCAPABLE
if the application may not start server-provided signon and
signoff transactions at the terminal resource.
CICS_EPI_SIGNON_UNKNOWN
if the CICS_EpiAddTerminal function was used to add the
terminal resource. (This value is also returned if the
CICS_EpiAddExTerminal function was used to add the
terminal resource and prerequisite changes have not been
applied to the server.)
This field is supported only for CICS_EPI_VERSION_200.
CICS_EpiEventData_t:
EPI constants and data structures
Purpose: The CICS_EpiEventData_t structure holds details of a
terminal-related event. Not all fields are valid for all events, and fields that
are not valid are set to nulls. This structure is an output from
CICS_EpiGetEvent.
Fields:
TermIndex
The terminal index for the terminal resource against which this event
occurred.
Event The event indicator; that is, one of the event codes listed in “EPI
events” on page 166.
EndReason
The reason for termination, if the event is a
CICS_EPI_EVENT_END_TERM or CICS_EPI_EVENT_END_TRAN
event.
TransId
A string specifying a transaction name. If the name is shorter than
CICS_EPI_TRANSID_MAX characters, it is padded with spaces to this
length, followed by a single null character.
Reserved1
A reserved field.
Chapter 4. C and COBOL 135

EPI constants and data structures
Prior to CICS Transaction Gateway Version 3.1, this field was called
AbendCode.
Data A pointer to a buffer that is updated with any terminal data stream
associated with the event.
On input the Data parameter should be set to point to a
CICS_EpiDetails_t structure on the first invocation of
CICS_EpiGetEvent for a terminal being added asynchronously. The
details structure is updated on return from CICS_EpiGetEvent.
Size The maximum size of the buffer addressed by Data. On return from
the CICS_EpiGetEvent call, this contains the actual length of data
returned.
EndReturnCode
A string containing the CICS_EPI_returncode.
This field is supported only for CICS_EPI_VERSION_200.
MapName
A string specifying the name of the map that was most recently
referenced in the MAP option of a SEND MAP command processed
for the terminal resource, if the event is a CICS_EPI_EVENT_SEND or
a CICS_EPI_EVENT_CONVERSE event. If the terminal resource is not
supported by BMS, or the server has no record of any map being sent,
the value returned is spaces. If the name is shorter than
CICS_EPI_MAPNAME_MAX characters, it is padded with spaces to
this length, followed by a single null character.
This field is supported only for CICS_EPI_VERSION_200.
MapSetName
A string specifying the name of the mapset that was most recently
referenced in the MAPSET option of a SEND MAP command
processed for the terminal resource, if the event is a
CICS_EPI_EVENT_SEND or a CICS_EPI_EVENT_CONVERSE event.
If the MAPSET option was not specified on the most recent request,
BMS used the map name as the mapset name. In both cases, the
mapset name used may have been suffixed by a terminal suffix. If the
terminal resource is not supported by BMS, or the server has no
record of any mapset being sent, the value returned is spaces. If the
name is shorter than CICS_EPI_MAPSETNAME_MAX characters, it is
padded with spaces to this length, followed by a single null character.
This field is supported only for CICS_EPI_VERSION_200.
Note: The Data and Size fields should be set before the call to
CICS_EpiGetEvent is made.
CICS_EpiSysError_t:
136 CICS Transaction Gateway: Programming Reference

Purpose: The CICS_EpiSysError_t structure holds system error information. It
is an output of CICS_EpiGetSysError.
This data structure is not supported for CICS_EPI_VERSION_200.
All error information is written to the CICS Transaction Gateway log file.
Fields:
Cause A value, specific to the operating environment, indicating the cause of
the last error.
Value A value, specific to the operating environment, indicating the nature
of the last error.
Msg A text message, specific to the operating environment, describing the
last error. If the message is shorter than CICS_EPI_ERROR_MAX, it is
padded with nulls to a length of CICS_EPI_ERROR_MAX + 1.
EPI functions
This section describes the functions provided by the EPI that can be called
from an application program:
v CICS_EpiInitialize
v CICS_EpiTerminate
v CICS_EpiListSystems
v CICS_EpiAddTerminal
v CICS_EpiAddExTerminal
v CICS_EpiInquireSystem
v CICS_EpiDelTerminal
v CICS_EpiPurgeTerminal
v CICS_EpiSetSecurity
v CICS_EpiStartTran
v CICS_EpiReply
v CICS_EpiATIState
v CICS_EpiSenseCode
v CICS_EpiGetEvent
v CICS_EpiGetSysError.
Table 1 on page 138 summarizes the functions of the interface, the parameters
passed to each function, and the possible return codes from each function.
The mapping of actual return code values to the symbolic names is contained
in the following file for the Windows operating systems:
C \include\cics_eci.h
Cobol \copybook\cicsepi.cbl
and in the following files for the UNIX operating systems:
EPI constants and data structures
Chapter 4. C and COBOL 137

EPI functions
C /include/cics_eci.h
Table 1. Summary of EPI functions
Function name Parameters Return codes: CICS_EPI_
CICS_EpiInitialize Version ERR_FAILED
ERR_IS_INIT
ERR_VERSION
NORMAL
CICS_EpiTerminate none ERR_FAILED
ERR_NOT_INIT
ERR_IN_CALLBACK
NORMAL
CICS_EpiListSystems NameSpace ERR_FAILED
Systems ERR_MORE_SYSTEMS
List
ERR_NO_SYSTEMS
ERR_NOT_INIT
ERR_NULL_PARM
ERR_IN_CALLBACK
NORMAL
CICS_EpiAddTerminal NameSpace ERR_FAILED
System ERR_NOT_INIT
Netname ERR_SYSTEM
DevType ERR_SECURITY
NotifyFn ERR_NULL_PARM
Details ERR_IN_CALLBACK
TermIndex ERR_SERVER_DOWN
NORMAL
138 CICS Transaction Gateway: Programming Reference
For CICS_EPI_VERSION_200
only:
ERR_TERMID_INVALID
ERR_MODELID_INVALID
ERR_NOT_3270_DEVICE
ERR_ALREADY_INSTALLED
ERR_SERVER_BUSY
ERR_RESOURCE_SHORTAGE
ERR_MAX_SESSIONS
ERR_MAX_SYSTEMS

EPI functions
Table 1. Summary of EPI functions (continued)
Function name Parameters Return codes: CICS_EPI_
CICS_EpiAddExTerminal System ERR_FAILED
Netname ERR_NOT_INIT
DevType ERR_SYSTEM
NotifyFn ERR_SECURITY
Details ERR_NULL_PARM
TermIndex ERR_VERSION
Attributes ERR_IN_CALLBACK
ERR_SERVER_DOWN
ERR_RESPONSE_TIMEOUT
ERR_SIGNON_NOT_POSS
ERR_PASSWORD_INVALID
ERR_ADDTYPE_INVALID
ERR_SIGNONCAP_INVALID
ERR_USERID_INVALID
ERR_TERMID_INVALID
ERR_MODELID_INVALID
ERR_NOT_3270_DEVICE
ERR_ALREADY_INSTALLED
ERR_CCSID_INVALID
ERR_SERVER_BUSY
ERR_RESOURCE_SHORTAGE
ERR_MAX_SESSIONS
ERR_MAX_SYSTEMS
NORMAL
CICS_EpiInquireSystem TermIndex ERR_BAD_INDEX
System ERR_FAILED
ERR_NOT_INIT
ERR_NULL_PARM
ERR_IN_CALLBACK
NORMAL
CICS_EpiDelTerminal TermIndex ERR_BAD_INDEX
ERR_FAILED
ERR_NOT_INIT
ERR_TRAN_ACTIVE
ERR_IN_CALLBACK
NORMAL
CICS_EpiPurgeTerminal TermIndex ERR_BAD_INDEX
ERR_FAILED
ERR_NOT_INIT
ERR_IN_CALLBACK
ERR_VERSION
NORMAL
Chapter 4. C and COBOL 139

EPI functions
Table 1. Summary of EPI functions (continued)
Function name Parameters Return codes: CICS_EPI_
CICS_EpiSetSecurity TermIndex ERR_NOT_INIT
UserId
ERR_BAD_INDEX
Password ERR_IN_CALLBACK
ERR_SYSTEM_ERROR
ERR_VERSION
ERR_PASSWORD_INVALID
ERR_USERID_INVALID
ERR_NULL_PASSWORD
ERR_NULL_USERID
NORMAL
CICS_EpiStartTran TermIndex ERR_ATI_ACTIVE
TransId ERR_BAD_INDEX
Data
ERR_FAILED
Size
ERR_NO_DATA
ERR_NOT_INIT
ERR_TTI_ACTIVE
ERR_IN_CALLBACK
ERR_SERVER_DOWN
ERR_RESOURCE_SHORTAGE
(v 200 only)
ERR_MAX_SESSIONS
(v 200 only)
NORMAL
CICS_EpiReply TermIndex ERR_BAD_INDEX
Data
ERR_FAILED
Size
ERR_NO_CONVERSE
ERR_NO_DATA
ERR_NOT_INIT
ERR_IN_CALLBACK
ERR_ABENDED (v 200 only)
ERR_SERVER_DOWN
NORMAL
CICS_EpiATIState TermIndex ERR_ATI_STATE
ATIState ERR_BAD_INDEX
ERR_FAILED
ERR_NOT_INIT
ERR_IN_CALLBACK
ERR_NULL_PARAM
NORMAL
140 CICS Transaction Gateway: Programming Reference

Table 1. Summary of EPI functions (continued)
Function name Parameters Return codes: CICS_EPI_
CICS_EpiSenseCode TermIndex ERR_BAD_INDEX
SenseCode ERR_FAILED
ERR_NOT_INIT
ERR_SENSE_CODE
ERR_IN_CALLBACK
ERR_VERSION
NORMAL
CICS_EpiGetEvent TermIndex ERR_BAD_INDEX
Wait
ERR_FAILED
ERR_MORE_DATA
ERR_MORE_EVENTS
ERR_NO_EVENT
ERR_NOT_INIT
ERR_WAIT
ERR_NULL_PARAM
ERR_IN_CALLBACK
NORMAL
CICS_GetSysError TermIndex ERR_NOT_INIT
SysErr
ERR_BAD_INDEX
ERR_FAILED
ERR_NULL_PARAM
ERR_VERSION
NORMAL
Refer to the definitions of the functions to discover the types and usage of the
parameters, the data structures used by the functions, and the meanings of the
return codes.
CICS_EpiInitialize
CICS_EpiInitialize Version
EPI functions
Purpose: The CICS_EpiInitialize function initializes the EPI. All other EPI
calls from this application are invalid before this call is made.
Parameters:
Version
The version of the EPI for which this application is coded. This makes
it possible for old applications to remain compatible with future
versions of the EPI. The version described here is
CICS_EPI_VERSION_200. See EPI versions, inCICS Transaction
Gateway: Programming Guide, for more information.
Chapter 4. C and COBOL 141

EPI functions
The EPI uses this parameter only for input.
Return codes:
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_IS_INIT
The EPI is already initialized.
CICS_EPI_ERR_VERSION
The EPI cannot support the version requested.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiTerminate
CICS_EpiTerminate
Purpose: The CICS_EpiTerminate function ends the application’s use of the
EPI, typically just before the application terminates. All other EPI calls (except
for CICS_EpiInitialize) are invalid when this call has completed.
The application should issue CICS_EpiDelTerminal calls before terminating,
to delete any terminal resources.
Parameters: None.
Return codes:
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_TTI_ACTIVE
A transaction started from the EPI is still active or a
CICS_EpiGetEvent call is still outstanding.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_NORMAL
The function completed successfully.
142 CICS Transaction Gateway: Programming Reference

CICS_EpiListSystems
CICS_EpiListSystems NameSpace
Systems
List
EPI functions
Purpose: The CICS_EpiListSystems function returns a list of CICS servers
that are candidates to act as servers for EPI requests. There is no guarantee
that a communications link exists between the CICS Transaction Gateway and
any server in the list, or that any of the servers is available to process
requests.
The list is returned as an array of system information structures, one element
for each CICS server. See “CICS_EpiSystem_t” on page 131 for the contents of
the structure.
EPI applications should call this function immediately after each
CICS_EpiInitialize call made to determine which CICS servers are available.
Parameters:
NameSpace
A pointer reserved for future use. Ensure that this is a null pointer.
Systems
A pointer to a number. On entry to the function, this number specifies
the number of elements in the array specified in the List parameter.
This value should accurately reflect the amount of storage that is
available to the EPI to store the result. On return, it contains the
actual number of servers found.
The EPI uses this parameter for both input and output.
List An array of CICS_EpiSystem_t structures that are filled in and
returned by the function. The application should provide the storage
for the array and must set the Systems parameter to indicate the
number of elements in the array. The first name in the list is the
default server. However, the way in which the default is defined is
operating system dependent.
The EPI uses this parameter only for output.
Return codes:
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_MORE_SYSTEMS
There was not enough space in the List array to store the details of all
Chapter 4. C and COBOL 143

EPI functions
the CICS servers found. The supplied array has been filled, and the
Systems parameter has been updated to contain the total number of
servers found, thus allowing you to reallocate an array of suitable size
and try the function again.
CICS_EPI_ERR_NO_SYSTEMS
No CICS servers can be located. In this case, the value returned in
Systems is zero.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_NULL_PARM
Systems is a null pointer.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_NORMAL
The function completed successfully. The number of systems found is
at least one, and does not exceed the value supplied as input in the
Systems parameter.
CICS_EpiAddTerminal
CICS_EpiAddTerminal NameSpace
System
NetName
DevType
NotifyFn
Details
TermIndex
Purpose: The CICS_EpiAddTerminal function installs a new terminal
resource, or reserves an existing terminal resource, for the application’s use. It
provides a terminal index, which should be used to identify the terminal
resource on all further EPI calls. It also provides the information defined in
the CICS_EpiDetails_t data structure.
There is a limit on the number of terminals you can add with this operation:
The maximum varies according to the resources available on the client system.
Note: The CICS_EpiAddTerminal function adds terminal resources whose
signon capability is dependant upon the server in which the terminal
resource is installed, for example, they would be signon incapable on
CICS Transaction Server for z/OS servers.
Parameters:
144 CICS Transaction Gateway: Programming Reference

EPI functions
NameSpace
A pointer reserved for future use. Ensure that this is a null pointer.
System
A pointer to a null-terminated string that specifies the name of the
server in which the terminal resource is to be installed or reserved. If
the name is shorter than CICS_EPI_SYSTEM_MAX characters, it must
be padded with nulls to a length of CICS_EPI_SYSTEM_MAX + 1.
If the string is all nulls, the default server is selected by the EPI. To
determine the name of the server chosen, use
CICS_EpiInquireSystem. (Specifying a null string is allowed only if
the EPI was initialized with EPI_VERSION_101, or greater.)
The EPI uses this parameter only for input.
NetName
A pointer to a null-terminated string that specifies the name of the
terminal resource to be installed or reserved, or null. The
interpretation of this name is server-dependent.
If a string is supplied that is shorter than
CICS_EPI_NETNAME_MAX, it must be padded with nulls to a length
of CICS_EPI_NETNAME_MAX + 1.
The string is transmitted to the server without conversion to
uppercase.
The characters used are translated from the client’s code page to an
EBCDIC code page before transmission. If the server uses an ASCII
code page, they will be retranslated. The only characters guaranteed
to be invariant under these translations are the uppercase characters A
to Z, and the numeric characters 0 to 9. Some EBCDIC servers
(Katakana and Hebrew character set A) do not use the standard
representations of the lowercase alphabetic characters; use them with
care when communicating with such servers.
The use of NetName is as follows:
1. If a name is supplied using the NetName, and it matches the
name of an existing terminal resource in the server, the server
attempts to reserve that terminal resource.
2. If a name is supplied, but it does not match the name of an
existing terminal resource in the server, the server installs a
terminal resource using the model terminal definition specified by
the DevType parameter described below, and gives it the input
name. (If DevType is a null pointer,
CICS_EPI_ERR_TERMID_INVALID is returned for
CICS_EPI_VERSION_200 or later, otherwise
CICS_EPI_ERR_FAILED is returned.)
Chapter 4. C and COBOL 145

EPI functions
3. If NetName is a null pointer, a terminal resource is installed using
the model terminal definition specified in DevType. IfDevType is
a null pointer, the selected terminal type is not predictable, so you
are advised to use DevType to ensure consistent results. The name
of the terminal resource is returned in the NetName field of the
CICS_EpiDetails_t structure.
The EPI uses this parameter only for input.
DevType
A pointer to a null-terminated string that is used in the server to
select a model terminal definition from which a terminal resource
definition is generated, or a null pointer.
If a string is supplied that is shorter than CICS_EPI_DEVTYPE_MAX
characters, it should be padded with nulls to a length of
CICS_EPI_DEVTYPE_MAX + 1.
The string is transmitted to the server without conversion to
uppercase.
The characters used are translated from the client’s code page to an
EBCDIC code page before transmission. If the server uses an ASCII
code page, they will be retranslated. The only characters guaranteed
to be invariant under these translations are the uppercase characters A
to Z, and the numeric characters 0 to 9. Some EBCDIC servers
(Katakana and Hebrew character set A) do not use the standard
representations of the lowercase alphabetic characters; use them with
care when communicating with such servers.
The EPI uses this parameter only for input.
NotifyFn
A pointer to a callback routine that is called whenever an event occurs
for the terminal resource, such as the arrival of an ATI request. If a
callback routine is not required, this parameter should be set to null.
The EPI uses this parameter only for input.
Details
A pointer to the CICS_EpiDetails_t structure that on return contains
various details about the terminal resource that was installed or
reserved.
The EPI uses the fields in this structure only for output.
TermIndex
A pointer to a terminal index for the terminal resource just installed or
reserved. The returned terminal index must be used as input to all
146 CICS Transaction Gateway: Programming Reference

EPI functions
further EPI function calls to identify the terminal resource to which
the function is directed. The terminal index supplied is the first
available integer starting from 0.
The EPI uses this parameter only for output.
Return codes:
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_SYSTEM
The specified server is not known to the client.
CICS_EPI_ERR_SECURITY
The server rejected the attempt for security reasons.
CICS_EPI_ERR_NULL_PARM
TermIndex was a null pointer.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_ERR_SERVER_DOWN
The function failed because the server was down.
CICS_EPI_ERR_TERMID_INVALID
The function failed because an invalid TermId was supplied.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_MODELID_INVALID
The function failed because an invalid Model terminal definition was
supplied.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_NOT_3270_DEVICE
The function failed because the device type supplied was not for a
3270 device.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_ALREADY_INSTALLED
The function failed because the terminal was already installed.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_SERVER_BUSY
The function failed because the server was busy.
This is supported for CICS_EPI_VERSION_200 only.
Chapter 4. C and COBOL 147

EPI functions
CICS_EPI_ERR_RESOURCE_SHORTAGE
The CICS server or CICS Transaction Gateway did not have enough
resources to complete the terminal install.
CICS_EPI_ERR_MAX_SESSIONS
There were not enough communication resources to satisfy this
request.
CICS_EPI_ERR_MAX_SYSTEMS
An attempt was made to start connections to more servers than your
configuration allows.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiAddExTerminal
CICS_EpiAddExTerminal System
NetName
DevType
NotifyFn
Details
TermIndex
Attributes
Purpose: Supported only for EPI Version 2 or later.
The CICS_EpiAddExTerminal function installs a new terminal resource, or
reserves an existing terminal resource, for the application’s use. It provides a
terminal index, which should be used to identify the terminal resource on all
further EPI calls. It also provides the information defined in the
CICS_EpiDetails_t data structure.
Some attributes, for example the character set and encoding scheme to be
used for 3270 data and the signon capability, may be determined by the
application. These attributes are specified in the CCSID and
SignonCapability fields in the CICS_EpiAttributes_t structure.
Parameters:
System
A pointer to a null-terminated string that specifies the name of the
server in which the terminal resource is to be installed or reserved. If
the name is shorter than CICS_EPI_SYSTEM_MAX characters, it must
be padded with nulls to a length of CICS_EPI_SYSTEM_MAX + 1.
If the string is all nulls, the default server is selected by the EPI. To
determine the name of the server chosen, use
CICS_EpiInquireSystem.
148 CICS Transaction Gateway: Programming Reference

EPI functions
The EPI uses this parameter only for input.
NetName
A pointer to a null-terminated string that specifies the name of the
terminal resource to be installed or reserved, or null. The
interpretation of this name is server-dependent.
If a string is supplied that is shorter than
CICS_EPI_NETNAME_MAX, it must be padded with nulls to a length
of CICS_EPI_NETNAME_MAX + 1.
The string is transmitted to the server without conversion to
uppercase.
The characters used are translated from the client’s code page to an
EBCDIC code page before transmission. If the server uses an ASCII
code page, they will be retranslated. The only characters guaranteed
to be invariant under these translations are the uppercase characters A
to Z, and the numeric characters 0 to 9. Some EBCDIC servers
(Katakana and Hebrew character set A) do not use the standard
representations of the lowercase alphabetic characters; use them with
care when communicating with such servers.
The use of NetName is as follows:
1. If a name is supplied using the NetName, and it matches the
name of an existing terminal resource in the server, the server
attempts to reserve that terminal resource.
2. If a name is supplied, but does not match the name of an existing
terminal resource in the server, the server installs a terminal
resource using the model terminal definition specified by the
DevType parameter described below, and gives it the input name.
(If DevType is a null pointer, CICS_EPI_ERR_TERMID_INVALID
is returned for CICS_EPI_VERSION_200 or later, otherwise
CICS_EPI_ERR_FAILED is returned.)
3. If NetName is a null pointer, a terminal resource is installed using
the model terminal definition specified in DevType. IfDevType is
a null pointer, the selected terminal type is not predictable, so you
are advised to use DevType to ensure consistent results. The name
of the terminal resource is returned in the NetName field of the
CICS_EpiDetails_t structure.
The EPI uses this parameter only for input.
DevType
A pointer to a null-terminated string that is used in the server to
select a model terminal definition from which a terminal resource
definition is generated, or a null pointer.
Chapter 4. C and COBOL 149

EPI functions
If a string is supplied that is shorter than CICS_EPI_DEVTYPE_MAX
characters, it should be padded with nulls to a length of
CICS_EPI_DEVTYPE_MAX + 1.
The string is transmitted to the server without conversion to
uppercase.
The characters used are translated from the client’s code page to an
EBCDIC code page before transmission. If the server uses an ASCII
code page, they will be retranslated. The only characters guaranteed
to be invariant under these translations are the uppercase characters A
to Z, and the numeric characters 0 to 9. Some EBCDIC servers
(Katakana and Hebrew character set A) do not use the standard
representations of the lowercase alphabetic characters; use them with
care when communicating with such servers.
The EPI uses this parameter only for input.
NotifyFn
A pointer to a callback routine that is called whenever an event occurs
for the terminal resource, such as the arrival of an ATI request. If a
callback routine is not required, this parameter should be set to null.
The EPI uses this parameter only for input.
Details
A pointer to the CICS_EpiDetails_t structure that on return contains
various details about the terminal resource that was installed or
reserved. For asynchronous calls, the Details parameter should be set
to NULL. If the pointer is not set to nulls, the details are added to the
structure when the request to install the terminal resource has
completed. For asynchronous calls this is done when the
CICS_EPI_EVENT_ADD_TERM event occurs.
The EPI uses the fields in this structure only for output.
TermIndex
A pointer to a terminal index for the terminal resource just installed or
reserved. The returned terminal index must be used as input to all
further EPI function calls to identify the terminal resource to which
the function is directed. The terminal index supplied is the first
available integer starting from 0.
The EPI uses this parameter only for output.
Attributes
A pointer to the CICS_EpiAttributes_t structure that specifies
attributes definable by the client application for the terminal resource
that is to be installed The structure must be set to nulls before use.
Default attributes are assumed if the pointer is set to null.
150 CICS Transaction Gateway: Programming Reference

The EPI uses this parameter only for input.
EPI functions
Return codes:
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_SYSTEM
The specified server is not known to the CICS Transaction Gateway.
CICS_EPI_ERR_SECURITY
The server rejected the attempt for security reasons.
CICS_EPI_ERR_NULL_PARM
TermIndex was a null pointer.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_ERR_RESPONSE_TIMEOUT
No response was received from the server within the specified
interval.
CICS_EPI_ERR_SIGNON_NOT_POSS
The server does not allow terminal resources to be installed as signon
capable.
CICS_EPI_ERR_SERVER_DOWN
The function failed because the server was down.
CICS_EPI_ERR_PASSWORD_INVALID
The length of the password exceeds CICS_EPI_PASSWORD_MAX.
CICS_EPI_ERR_ADDTYPE_INVALID
The value assigned to the EpiAddType field in the
CICS_EpiAttributes_t structure is neither CICS_EPI_ADD_ASYNC
nor CICS_EPI_ADD_SYNC.
CICS_EPI_ERR_SIGNONCAP_INVALID
The value assigned to the SignonCapability field in the
CICS_EpiAttributes_t structure is neither
CICS_EPI_SIGNON_CAPABLE nor CICS_EPI_SIGNON_INCAPABLE.
CICS_EPI_ERR_USERID_INVALID
The length of the userid exceeds CICS_EPI_USERID_MAX.
CICS_EPI_ERR_TERMID_INVALID
The function failed because an invalid TermId was supplied.
This is supported for CICS_EPI_VERSION_200 only.
Chapter 4. C and COBOL 151

EPI functions
CICS_EPI_ERR_MODELID_INVALID
The function failed because an invalid Model terminal definition was
supplied.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_NOT_3270_DEVICE
The function failed because the device type supplied was not for a
3270 device.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_ALREADY_INSTALLED
The function failed because the terminal was already installed.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_CCSID_INVALID
The function failed because an invalid CCSID was supplied.
For details on the CCSID values for various character sets, see Data
conversion when using the Client daemon, intheCICS Transaction
Gateway: Administration book for your operating system.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_SERVER_BUSY
The function failed because the server was busy.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_VERSION
The function is not supported for the version at which the EPI was
initialized.
CICS_EPI_ERR_RESOURCE_SHORTAGE
The CICS server or CICS Transaction Gateway did not have enough
resources to complete the terminal install.
CICS_EPI_ERR_MAX_SESSIONS
There were not enough communication resources to satisfy this
request.
CICS_EPI_ERR_MAX_SYSTEMS
An attempt was made to start connections to more servers than your
configuration allows.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiInquireSystem
CICS_EpiInquireSystem TermIndex
System
152 CICS Transaction Gateway: Programming Reference

Purpose: The CICS_EpiInquireSystem function returns the name of the
server on which a given terminal resource (identified by its terminal index) is
installed.
Parameters:
TermIndex
The terminal index of the terminal resource whose location is to be
determined.
The EPI uses this parameter only for input.
System
A pointer to a string of length CICS_ECI_SYSTEM_MAX +1inwhich
the name of the server will be returned.
The EPI uses this parameter only for output.
Return codes:
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_NULL_PARM
System was a null pointer.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_NORMAL
The function completed successfully. The name of the server is
returned in the System parameter padded with nulls to a length of
CICS_EPI_SYSTEM_MAX +1.
CICS_EpiDelTerminal
CICS_EpiDelTerminal TermIndex
EPI functions
Purpose: The CICS_EpiDelTerminal function deletes a previously added
terminal resource. The application should not consider the deletion complete
until it receives the corresponding CICS_EPI_EVENT_END_TERM event. The
terminal index remains allocated until a CICS_EpiGetEvent call retrieves the
CICS_EPI_EVENT_END_TERM event. A call to this function fails if the
Chapter 4. C and COBOL 153

EPI functions
terminal resource is currently running a transaction. To ensure that a terminal
resource is deleted, the application must wait until the current transaction
finishes and process all outstanding events before issuing the
CICS_EpiDelTerminal call.
If the terminal resource was autoinstalled, its definition is deleted from the
server. When a CICS_EpiDelTerminal call has completed successfully for a
terminal resource, use of the terminal index is restricted to CICS_EpiGetEvent
and CICS_EpiGetSysError calls until the application has received the
corresponding CICS_EPI_EVENT_END_TERM event.
Parameters:
TermIndex
The terminal index of the terminal resource to be deleted.
The EPI uses this parameter only for input.
Return codes:
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_TRAN_ACTIVE
A transaction is currently running against the terminal resource, or
there are unprocessed events for the terminal resource.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiPurgeTerminal
CICS_EpiPurgeTerminal TermIndex
Purpose: Supported only for EPI Version 2 or later.
The CICS_EpiPurgeTerminal function purges a previously added terminal
resource. The application should not consider the deletion complete until it
receives the corresponding CICS_EPI_EVENT_END_TERM event.
154 CICS Transaction Gateway: Programming Reference

The CICS_EpiPurgeTerminal call differs from the CICS_EpiDelTerminal call
in that the application does not have to wait until the current transaction
finishes or process all outstanding events before issuing the call.
If the terminal resource was autoinstalled, its definition is deleted from the
server.
This purge function does not cancel ATI requests queued against the terminal.
Parameters:
TermIndex
The terminal index of the terminal resource to be deleted.
The EPI uses this parameter only for input.
Return codes:
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_ERR_VERSION
The function is not supported for the version at which the EPI was
initialized.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiSetSecurity
CICS_EpiSetSecurity TermIndex
UserId
Password
Purpose:
Supported only for EPI Version 2 or later.
EPI functions
The CICS_EpiSetSecurity function allows a client application to specify a
userid and password to be associated with a terminal resource previously
installed as signon incapable.
Chapter 4. C and COBOL 155

EPI functions
The CICS_EpiSetSecurity function may be invoked at any time; the userid
and password will be used as further transactions are started for the terminal
resource. A CICS Transaction Gateway determined userid and password will
be used if the function either has not been invoked for the terminal resource
or has been invoked and has set the userid, and by implication the password,
to nulls.
Note that the client application is responsible for verifying the userid and
password.
Parameters:
TermIndex
The terminal index of the terminal.
The EPI uses this parameter only for input.
UserId
A pointer to a null-terminated string that specifies the userid. If the
userid is shorter than CICS_EPI_USERID_MAX characters, it must be
padded with nulls to a length of CICS_EPI_USERID_MAX+1.
The EPI uses this parameter only for input.
Password
A pointer to a null-terminated string that specifies the password. If
the password is shorter than CICS_EPI_PASSWORD_MAX characters,
it must be padded with nulls to a length of
CICS_EPI_PASSWORD_MAX+1.
The EPI uses this parameter only for input.
Return codes:
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_ERR_SYSTEM_ERROR
An internal system error occurred.
CICS_EPI_ERR_VERSION
The function is not supported for the version at which the EPI was
initialized.
CICS_EPI_ERR_NULL_PASSWORD
Password was a null pointer.
156 CICS Transaction Gateway: Programming Reference

CICS_EPI_ERR_NULL_USERID
Userid was a null pointer.
CICS_EPI_ERR_PASSWORD_INVALID
The length of the password exceeds CICS_EPI_PASSWORD_MAX.
CICS_EPI_ERR_USERID_INVALID
The length of the userid exceeds CICS_EPI_USERID_MAX.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiStartTran
Purpose:
CICS_EpiStartTran TermIndex
TransId
Data
Size
EPI functions
The CICS_EpiStartTran function starts a new transaction from a terminal
resource, or continues a pseudoconversation.
v Starting a new transaction—do this after CICS_EpiAddTerminal, or after a
CICS_EPI_EVENT_END_TRAN event indicated that the previous
transaction did not specify a transaction to process the next input from the
terminal resource.
v Continuing a pseudoconversation—do this after a
CICS_EPI_EVENT_END_TRAN event that indicated that the previous
transaction specified did specify a transaction to process the next input
from the terminal resource.
If the call is successful, no further start requests can be issued for this terminal
resource until the transaction ends; this is indicated by the
CICS_EPI_EVENT_END_TRAN event.
Parameters:
TermIndex
The terminal index of the terminal resource that is to run the
transaction.
The EPI uses this parameter only for input.
TransId
A pointer to a string specifying the transaction to be run, or the null
pointer. If a new transaction is being started, and this input is the null
pointer, the name of the transaction is extracted from the data stream
Chapter 4. C and COBOL 157

EPI functions
supplied in the Data parameter. If a pseudoconversation is being
continued, and the pointer is not null, the string must be the name of
the transaction returned in the preceding
CICS_EPI_EVENT_END_TRAN event for this terminal resource. If the
pointer is not null, and the string is shorter than
CICS_EPI_TRANSID_MAX characters, it should be padded with
spaces to this length.
The EPI uses this parameter only for input.
Data A pointer to the 3270 data stream to be associated with the
transaction. This parameter must not be a null pointer, because the
data stream must contain at least an AID byte.
If a new transaction is being started, and the TransId parameter is the
null pointer, the data stream must be at least 4 bytes long, must
contain the name of the transaction to be started, and might contain
data to be supplied to the transaction on its first EXEC CICS RECEIVE
command.
If a new transaction is being started, and the TransId parameter is not
the null pointer, the data stream might be only one byte (an AID
byte), or 3 bytes (an AID byte and a cursor address), or longer than 3
bytes (an AID byte, a cursor address, and data and SBA commands).
In the last case, the data is supplied to the transaction program on the
first EXEC CICS RECEIVE command.
If a pseudoconversation is being continued, the data stream might be
only one byte (an AID byte), or 3 bytes (an AID byte and a cursor
address), or longer than 3 bytes (an AID byte, a cursor address, and
data and SBA commands). In the last case the data is supplied to the
transaction program on the first EXEC CICS RECEIVE command.
The details of the format of 3270 data streams for CICS are described
in 3270 data streams for the EPI, inCICS Transaction Gateway:
Programming Guide.
The length of the 3270 data stream must not exceed the value that
was returned in MaxData in CICS_EpiDetails_t when the terminal
resource was installed with CICS_EpiAddTerminal.
The EPI uses this parameter only for input.
Size The size in bytes of the initial data to be passed to the transaction.
The EPI uses this parameter only for input.
Note: The application might expect a terminal resource to be free to start a
transaction and yet get an unexpected return code of
CICS_EPI_ERR_ATI_ACTIVE from a call to CICS_EpiStartTran. If this
happens, it means that the EPI has started an ATI request against the
158 CICS Transaction Gateway: Programming Reference

terminal resource and issued the corresponding
CICS_EPI_EVENT_START_ATI event, but the application has not yet
retrieved the event by issuing a CICS_EpiGetEvent call.
Return codes:
CICS_EPI_ERR_ATI_ACTIVE
An ATI transaction is active for this terminal resource.
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NO_DATA
No initial data was supplied.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_TTI_ACTIVE
A transaction started from the EPI is already active for this terminal
resource.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_ERR_SERVER_DOWN
The function failed because the server was down.
CICS_EPI_ERR_RESOURCE_SHORTAGE
The CICS server or CICS Transaction Gateway did not have enough
resources to complete the terminal install.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_ERR_MAX_SESSIONS
There were not enough communication resources to satisfy this
request.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiReply
CICS_EpiReply TermIndex
Data
Size
EPI functions
Chapter 4. C and COBOL 159

EPI functions
Purpose: The CICS_EpiReply function sends data from a terminal resource
to a CICS transaction. It should only be issued in response to a
CICS_EPI_EVENT_CONVERSE event.
Parameters:
TermIndex
The terminal index of the terminal resource from which the data is
being sent.
The EPI uses this parameter only for input.
Data A pointer to the 3270 data stream to be sent to the transaction. This
parameter must not be a null pointer, because the data stream must
contain at least an AID byte. The data stream might be one byte (an
AID byte), 3 bytes (an AID byte and a cursor address), or more than 3
bytes (an AID byte, a cursor address, and data and SBA commands).
In the last case, what follows the cursor address is supplied to the
transaction program on the first EXEC CICS RECEIVE command.
The length of the 3270 data stream must not exceed the value that
was returned in MaxData in CICS_EpiDetails_t when the terminal
resource was installed with CICS_EpiAddTerminal.
The EPI uses this parameter only for input.
Size The size of the data in bytes.
The EPI uses this parameter only for input.
Return codes:
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NO_CONVERSE
No reply is expected by the terminal resource.
CICS_EPI_ERR_NO_DATA
No reply data was supplied.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_ERR_SERVER_DOWN
The function failed because the server was down.
160 CICS Transaction Gateway: Programming Reference

CICS_EPI_ERR_ABENDED
The read timeout period has expired and the conversation has
abended, but the CICS_EPI_EVENT_END_TRAN event has not yet
been received by the application.
This is supported for CICS_EPI_VERSION_200 only.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiATIState
CICS_EpiATIState TermIndex
ATIState
EPI functions
Purpose: The CICS_EpiATIState function allows the calling application to
query and alter the way in which ATI requests for a terminal resource are
handled. If ATI requests are enabled (CICS_EPI_ATI_ON) and an ATI request
is issued in the server, the request is started when the terminal resource
becomes free. If ATI requests are held (CICS_EPI_ATI_HOLD), any ATI
requests issued are queued, and started when ATI requests are next enabled.
The state for ATI requests after a CICS_EpiAddTerminal call is
CICS_EPI_ATI_HOLD. The EPI application may change the state to
CICS_EPI_ATI_ON when it is ready to allow ATI requests to be processed.
(The server also maintains a ATI state for terminal resources, which is
independent of the ATI state maintained in the EPI. Changes to the ATI state
on the server do not affect the ATI status in the EPI.)
Parameters:
TermIndex
The terminal index of the terminal resource whose ATI state is
required.
The EPI uses this parameter only for input.
ATIState
The EPI uses this parameter for both input and output depending on
the input value as follows:
CICS_EPI_ATI_ON
Enable ATI requests, and return the previous ATI state in this
parameter.
CICS_EPI_ATI_HOLD
Hold ATI requests until they are next enabled, and return the
previous ATI state in this parameter.
Chapter 4. C and COBOL 161

EPI functions
CICS_EPI_ATI_QUERY
Do not change the ATI state; just return the current state in
this parameter.
Return codes:
CICS_EPI_ERR_ATI_STATE
An invalid ATIState value was provided.
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_NULL_PARAM
ATIState was a null pointer.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiSenseCode
CICS_EpiSenseCode TermIndex
SenseCode
Purpose: This function allows the calling application to inform the EPI of
any errors in the 3270 data sent by a transaction.
Not supported for EPI Version 2.
Parameters:
TermIndex
The terminal index of the terminal resource for which the error is to
be raised.
The EPI uses this parameter only for input.
SenseCode
The sense code failure reason, which can be one of the following
values:
CICS_EPI_SENSE_OPCHECK
Errors were detected in the 3270 data stream.
162 CICS Transaction Gateway: Programming Reference

CICS_EPI_SENSE_REJECT
Invalid 3270 commands were received.
The EPI uses this parameter only for input.
Return codes:
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_SENSE_CODE
An invalid sense code was provided.
CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_VERSION
The function is not supported for the version at which the EPI was
initialized.
CICS_EPI_NORMAL
The function completed successfully.
CICS_EpiGetEvent
CICS_EpiGetEvent TermIndex
Wait
Event
EPI functions
Purpose: The CICS_EpiGetEvent function obtains information about an
event that has occurred for a terminal resource.
Remember that this call may be attempted only from the application, not from
the callback routine.
Parameters:
TermIndex
The terminal index of the terminal resource for which to obtain an
event. This can be set to the constant CICS_EPI_TERM_INDEX_NONE
to indicate that the next event for any terminal resource used by this
application is to be returned. The application can examine the
Chapter 4. C and COBOL 163

EPI functions
TermIndex field in the returned CICS_EpiEventData_t structure to
determine the terminal resource against which the event was
generated.
The EPI uses this parameter for both input and output.
Wait An indication of what should happen if no event has been generated
for the terminal resource. Use one of the following values:
CICS_EPI_WAIT
Do not return until the next event occurs.
CICS_EPI_NOWAIT
Return immediately with an error code. This option is used if
the application elects to poll for events.
The EPI uses this parameter only for input.
Event A pointer to a CICS_EpiEventData_t structure that on return contains
the details of the event that occurred. The Data field in the structure
should be set to point to the data buffer that is updated with any
terminal data stream associated with the event. The Size field should
be set to indicate the maximum size of this buffer, and is updated to
contain the actual length of data returned.
Return codes:
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_MORE_DATA
The supplied data buffer was not large enough to contain the terminal
data; the data has been truncated.
CICS_EPI_ERR_MORE_EVENTS
An event was successfully obtained, but there are more events
outstanding against this terminal resource.
CICS_EPI_ERR_NO_EVENT
No events are outstanding for this terminal resource.
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has not been executed.
CICS_EPI_ERR_WAIT
The Wait parameter is not valid.
CICS_EPI_ERR_NULL_PARM
Event is a null pointer.
164 CICS Transaction Gateway: Programming Reference

CICS_EPI_ERR_IN_CALLBACK
The function was called from a callback routine.
CICS_EPI_NORMAL
The function completed successfully, and there are no more events.
CICS_EpiGetSysError
CICS_EpiGetSysError TermIndex
SysErr
Purpose: The CICS_EpiGetSysError function obtains detailed information
describing the last error that occurred when the CICS_EPI_ERR_FAILED
return code was generated. The values returned in the Cause and Value fields
in the supplied SysErr parameter can be used to further qualify the return
code from any other EPI function. These values are environment-dependent.
You might need to consult documentation for your CICS Transaction Gateway
environment, and the documentation for the appropriate CICS server.
Not supported for EPI Version 2.
The Msg field in the supplied SysErr parameter may return a message,
specific to the operating environment, describing the error that occurred. If no
message is available, this field is set to nulls.
Note: This function is reserved for backward compatibility. No information is
returned, and all system errors are written to the CICS Transaction
Gateway’s error log.
Parameters:
TermIndex
The terminal index of the terminal resource for which to obtain the
detailed error code. This parameter may be set to the constant
CICS_EPI_TERM_INDEX_NONE, if further error information
associated with a CICS_EpiInitialize, CICS_EpiTerminate,
CICS_EpiListSystems, orCICS_EpiAddTerminal call is required.
The EPI uses this parameter only for input.
SysErr
A pointer to a CICS_EpiSysError_t structure that, on return, contains
the system error information.
The EPI uses the structure only for output.
Return codes:
EPI functions
Chapter 4. C and COBOL 165

EPI functions
CICS_EPI_ERR_NOT_INIT
CICS_EpiInitialize has never been called. (If a CICS_EpiInitialize call
is made and fails, CICS_EpiGetSysError will still succeed.)
CICS_EPI_ERR_BAD_INDEX
The TermIndex value is not a valid terminal index.
CICS_EPI_ERR_FAILED
The function failed for an unexpected reason.
CICS_EPI_ERR_NULL_PARM
SysErr is a null pointer.
CICS_EPI_VERSION
The funcion is not supported for the version at which the EPI was
initialized.
CICS_EPI_NORMAL
The function completed successfully.
EPI events
EPI events occur when CICS has data to pass to the EPI application. The
application can handle EPI events in a variety of ways. See Events and
callbacks, inCICS Transaction Gateway: Programming Guide. Whichever
mechanism is used, the data from CICS is obtained by calling
CICS_EpiGetEvent.
CICS_EPI_EVENT_ADD_TERM
Purpose: The CICS_EPI_EVENT_ADD_TERM event indicates that an
asynchronous request to install a terminal resource has completed. If the
terminal resource was installed details will have been placed in the
CICS_EpiDetails_t structure, pointed to by Data.
Fields completed:
Event The CICS_EPI_EVENT_ADD_TERM event code.
EndReturnCode
The reason for termination. Refer to the CICS_EpiAddExTerminal
function for details of return codes.
Data A pointer to the CICS_EpiDetails_t structure that is updated with the
terminal details, if the EndReturnCode is CICS_EPI_NORMAL.
CICS_EPI_EVENT_SEND
Purpose: The CICS_EPI_EVENT_SEND event indicates that a transaction has
sent some 3270 data to a terminal resource, typically as a result of an EXEC
CICS SEND command. No reply is expected, and none should be attempted.
166 CICS Transaction Gateway: Programming Reference

Fields completed:
Event The CICS_EPI_EVENT_SEND event code.
Data A pointer to the buffer that is updated to contain the data sent by the
transaction. See 3270 data streams for the EPI, inCICS Transaction
Gateway: Programming Guide, for details of the data stream format.
Size The length of the data in the Data buffer.
CICS_EPI_EVENT_CONVERSE
Purpose: The CICS_EPI_EVENT_CONVERSE event indicates that a
transaction is expecting a reply as a result of either an EXEC CICS RECEIVE
command, or an EXEC CICS CONVERSE command.
The application should issue a CICS_EpiReply call to return the data to CICS,
as follows:
v If the transaction has issued an EXEC CICS RECEIVE command without
specifying the BUFFER option, the buffer might contain data sent from the
transaction, or it might be empty. If there is data to process, deal with it
before replying. Send the reply when the data to be sent is available.
v If the transaction has issued an EXEC CICS RECEIVE BUFFER command,
the data buffer contains the 3270 Read Buffer command and the Size field
is set to 1. The reply should be sent immediately.
Fields completed:
Event The CICS_EPI_EVENT_CONVERSE event code.
Data A pointer to the buffer that is updated to contain the data sent by the
transaction, as defined above.
Size The length of the data in the buffer. This may be set to zero to
indicate that no data was sent, but a reply is still expected.
CICS_EPI_EVENT_END_TRAN
EPI events
Purpose: The CICS_EPI_EVENT_END_TRAN event indicates the end of a
transaction that was running against a terminal resource. If the transaction
failed, the EndReason and EndReturnCode specify the cause. If the
transaction completed normally, the EndReason field is set to
CICS_EPI_TRAN_NO_ERROR and EndReturnCode is set to
CICS_EPI_NORMAL. If the transaction was pseudoconversational, the
TransId field contains the name of the next transaction required. The
application should start this transaction by issuing a CICS_EpiStartTran call.
Chapter 4. C and COBOL 167

EPI events
The CICS_EPI_EVENT_END_TRAN event occurs when a transaction running
against a terminal resource abends or ends following execution of a RETURN
command for which the IMMEDIATE option was not specified.
Fields completed:
Event The CICS_EPI_EVENT_END_TRAN event code.
EndReason
An indication of what caused the end transaction event. It can be one
of the following values:
CICS_EPI_TRAN_NO_ERROR
Normal transaction termination.
CICS_EPI_TRAN_NOT_STARTED
The transaction failed to start.
CICS_EPI_TRAN_STATE_UNKNOWN
The transaction failed to complete.
CICS_EPI_READTIMEOUT_EXPIRED
The read timout expired.
TransId
The name of the next transaction to start, if the previous transaction
was pseudoconversational. This name is 4 characters long and
null-terminated. If there is no next transaction, the field is set to nulls.
EndReturnCode
A string containing the CICS_EPI_returncode.
CICS_EPI_EVENT_START_ATI
Purpose: The CICS_EPI_EVENT_START_ATI event indicates that an ATI
transaction has been started against the terminal resource. If the terminal
resource receives an ATI request while it is running another transaction, the
request is held until the transaction ends. The transaction is then started on
behalf of the terminal resource, and the CICS_EPI_EVENT_START_ATI event
is generated to inform the application.
Fields completed:
Event The CICS_EPI_EVENT_START_ATI event code.
TransId
The name of the transaction that was started. This name is 4
characters long and null-terminated.
168 CICS Transaction Gateway: Programming Reference

External Security Interface
CICS_EPI_EVENT_END_TERM
Purpose: The CICS_EPI_EVENT_END_TERM event indicates that a terminal
resource no longer exists. After this event, the terminal index that was
previously used for the terminal resource is not valid. If the EPI detects that a
CICS server has shut down, CICS_EPI_EVENT_END_TERM events are
generated for all terminal resources that the application has installed in that
server and not subsequently deleted.
Fields completed:
Event The CICS_EPI_EVENT_END_TERM event code.
EndReason
An indication of why the terminal resource was deleted. It can be one
of the following values:
CICS_EPI_END_SIGNOFF
The terminal resource was signed off. This can be as a result
of running the CESF transaction or of calling the
CICS_EpiDelTerminal function.
CICS_EPI_END_SHUTDOWN
The CICS server is shutting down.
CICS_EPI_END_OUTSERVICE
The terminal resource has been switched out of service.
CICS_EPI_END_UNKNOWN
An unexpected error has occurred.
CICS_EPI_END_FAILED
An attempt to delete a terminal resource failed.
ESI constants and data structures
This section describes the constants and data structures that you need to use
the ESI.
ESI constants
The following constants are referred to symbolically in the descriptions of the
ESI data structures, and functions in this Chapter. Their values are given here
to help you understand the descriptions. However, your code should always
use the symbolic names of ESI constants provided for the programming
language you are using.
Lengths of fields
v CICS_ESI_PASSWORD_MAX (10)
EPI events
Chapter 4. C and COBOL 169

ESI constants and data structures
v CICS_ESI_SYSTEM_MAX (8)
v CICS_ESI_USERID_MAX (10)
ESI data structures
The following data structures are available for use with the ESI.
v CICS_EsiDate_t
v CICS_EsiTime_t
v CICS_EsiDetails_t
In the descriptions of the fields in the data structures, fields described as
strings are null-terminated strings.
CICS_EsiDate_t:
Purpose: The CICS_EsiDate_t structure contains a date represented as year,
month, and day.
Fields:
Year 4-digit year held in cics_ushort_t format.
Month
Month held in cics_ushort_t format; values range from 1 to 12 with 1
representing January.
Day Day held in cics_ushort_t format; values range from 1 to 31 with 1
representing the first day of the month.
CICS_EsiTime_t:
Purpose: The CICS_EsiTime structure contains a time represented as hours,
minutes, seconds, and hundredths of a second.
Fields:
Hours Hours held in cics_ushort_t format; values range from 0 to 23.
Minutes Minutes held in cics_ushort_t format; values range from 0 to
59.
Seconds Seconds held in cics_ushort_t format; values range from 0 to
59.
Hundredths Hundredths of a second held in cics_ushort_t format; values
range from 0 to 99.
CICS_EsiDetails_t:
170 CICS Transaction Gateway: Programming Reference

Purpose: The CICS_EsiDetails_t structure contains information returned from
a successful invocation of either the CICS_VerifyPassword or the
CICS_ChangePassword functions.
Fields:
LastVerifiedDate
The date on which the password was last verified.
LastVerifiedTime
The time at which the password was last verified.
ExpiryDate
The date on which the password will expire.
ExpiryTime
The time at which the password will expire.
LastAccessDate
The date on which the userid was last accessed.
LastAccessTime
The time at which the userid was last accessed.
InvalidCount
The number of times that an invalid password has been entered for
the userid.
ESI functions
This section describes the functions provided by the ESI that can be called
from an application program:
v CICS_VerifyPassword
v CICS_ChangePassword
v CICS_SetDefaultSecurity
CICS_VerifyPassword
CICS_VerifyPassword UserId
Password
System
Details
Purpose: The CICS_VerifyPassword function allows a client application to
verify that a password matches the password recorded by an external security
manager for a specified userid.
Note that the external security manager is assumed to be located in a server
to which the client is connected.
Parameters:
ESI constants and data structures
Chapter 4. C and COBOL 171

ESI functions
UserId
Password
System
172 CICS Transaction Gateway: Programming Reference
A pointer to a null-terminated string that specifies the userid
whose password is to be verified. If the userid is shorter than
CICS_ESI_USERID_MAX characters, it must be padded with
nulls to a length of CICS_ESI_USERID_MAX+1.
The ESI uses this parameter only for input.
A pointer to a null-terminated string that specifies the
password to be checked by the external security manager for
the specified userid. If the password is shorter than
CICS_ESI_PASSWORD_MAX characters, it must be padded
with nulls to a length of CICS_ESI_PASSWORD_MAX+1.
The ESI uses this parameter only for input.
A pointer to a null-terminated string that specifies the name of
the server in which the password is to be verified. If the name
is shorter than CICS_ESI_SYSTEM_MAX characters, it must be
padded with nulls to a length of CICS_ESI_SYSTEM_MAX+1.
If the string is all nulls, the default server is selected.
The ESI uses this parameter only for input.

Details
ESI functions
A pointer to the CICS_EsiDetails_t structure that on return
contains further information returned by the external security
manager.
The ESI uses the fields in this structure only for output.
Return codes:
CICS_ESI_NO_ERROR
The function completed successfully.
CICS_ESI_ERR_CALL_FROM_CALLBACK
The function was invoked from a callback routine.
CICS_ESI_ERR_SYSTEM_ERROR
An internal system error occurred.
CICS_ESI_ERR_NO_CICS
The CICS Transaction Gateway is unavailable, or the specified server
is unavailable.
CICS_ESI_ERR_CICS_DIED
The specified server is no longer available.
CICS_ESI_ERR_RESOURCE_SHORTAGE
The CICS Transaction Gateway did not have enough resources to
complete the request.
CICS_ESI_ERR_NO_SESSIONS
The application has as many outstanding ECI and EPI requests as the
configuration will support.
CICS_ESI_ERR_UNKNOWN_SERVER
The requested server could not be located. Only servers returned by
the CICS_EciListSystems and CICS_EpiListSystems functions are
acceptable.
CICS_ESI_ERR_MAX_SESSIONS
There were not enough communications resources to satisfy the
request. Consult the documentation for your CICS Transaction
Gateway or server to see how to control the number of servers you
can use.
CICS_ESI_ERR_MAX_SYSTEMS
You tried to start requests to more servers than your configuration
allows. Consult the documentation for your CICS Transaction
Gateway or server to see how to control the number of servers you
can use.
CICS_ESI_ERR_NULL_USERID
The userid is set to nulls.
Chapter 4. C and COBOL 173

ESI functions
CICS_ESI_ERR_NULL_PASSWORD
The password is set to nulls.
CICS_ESI_ERR_PEM_NOT_SUPPORTED
Password expiry managment is supported only for communications
with the requested server over SNA and TCP62.
CICS_ESI_ERR_PEM_NOT_ACTIVE
The requested server does not support password expiry management.
CICS_ESI_ERR_PASSWORD_EXPIRED
The password has expired.
CICS_ESI_ERR_PASSWORD_INVALID
The password is invalid.
CICS_ESI_ERR_USERID_INVALID
The userid is not known to the external security manager.
CICS_ESI_ERR_SECURITY_ERROR
An error has been detected by the external security manager. The
most likely explanation is that the userid has been revoked.
The mapping of actual return code values to the symbolic names is contained
in the \include\cics_esi.h file for CICS Transaction Gateway
for Windows. and in the /include/cics_esi.h file for CICS
Transaction Gateway for UNIX operating systems. COBOL users can find it in
the \copybook\cicsesi.cbl file.
CICS_ChangePassword
CICS_ChangePassword UserId
OldPassword
NewPassword
System
Details
Purpose: The CICS_ChangePassword function allows a client application to
change the password recorded by an external security manager for a specified
userid.
Note that the external security manager is assumed to be located in a server
to which the CICS Transaction Gateway is connected.
Parameters:
UserId
174 CICS Transaction Gateway: Programming Reference
A pointer to a null-terminated string that specifies the userid
whose password is to be changed. If the userid is shorter than

CICS_ESI_USERID_MAX characters, it must be padded with
nulls to a length of CICS_ESI_USERID_MAX+1.
The ESI uses this parameter only for input.
OldPassword
A pointer to a null-terminated string that specifies the current
password for the specified userid. If the password is shorter
than CICS_ESI_PASSWORD_MAX characters, it must be
padded with nulls to a length of
CICS_ESI_PASSWORD_MAX+1.
The ESI uses this parameter only for input.
NewPassword
A pointer to a null-terminated string that specifies the new
password for the specified userid. If the password is shorter
than CICS_ESI_PASSWORD_MAX characters, it must be
padded with nulls to a length of
CICS_ESI_PASSWORD_MAX+1.
The password is changed only if the currently password is
correctly specified.
The ESI uses this parameter only for input.
System
A pointer to a null-terminated string that specifies the name of
the server in which the password is to be verified. If the name
is shorter than CICS_ESI_SYSTEM_MAX characters, it must be
padded with nulls to a length of CICS_ESI_SYSTEM_MAX+1.
If the string is all nulls, the default server is selected.
The ESI uses this parameter only for input.
Details
A pointer to the CICS_EsiDetails_t structure that on return
contains further information returned by the external security
manager.
The ESI uses the fields in this structure only for output.
Return codes:
CICS_ESI_NO_ERROR
The function completed successfully.
CICS_ESI_ERR_CALL_FROM_CALLBACK
The function was invoked from a callback routine.
ESI functions
Chapter 4. C and COBOL 175

ESI functions
CICS_ESI_ERR_SYSTEM_ERROR
An internal system error occurred.
CICS_ESI_ERR_NO_CICS
The CICS Transaction Gateway is unavailable, or the specified server
is unavailable.
CICS_ESI_ERR_CICS_DIED
The specified server is no longer available. To confirm that the
password has been changed, use the CICS_VerifyPassword function.
CICS_ESI_ERR_RESOURCE_SHORTAGE
The CICS Transaction Gateway did not have enough resources to
complete the request.
CICS_ESI_ERR_NO_SESSIONS
The application has as many outstanding ECI and EPI requests as the
configuration will support.
CICS_ESI_ERR_UNKNOWN_SERVER
The requested server could not be located. Only servers returned by
the CICS_EciListSystems and CICS_EpiListSystems functions are
acceptable.
CICS_ESI_ERR_MAX_SESSIONS
There were not enough communications resources to satisfy the
request. Consult the documentation for your CICS Transaction
Gateway or server to see how to control the number of servers you
can use.
CICS_ESI_ERR_MAX_SYSTEMS
You tried to start requests to more servers than your configuration
allows. Consult the documentation for your CICS Transaction
Gateway or server to see how to control the number of servers you
can use.
CICS_ESI_ERR_NULL_USERID
The userid is set to nulls.
CICS_ESI_ERR_NULL_OLD_PASSWORD
The current password is set to nulls.
CICS_ESI_ERR_NULL_NEW_PASSWORD
The new password is set to nulls.
CICS_ESI_ERR_PEM_NOT_SUPPORTED
Password expiry management is supported only for communications
with the requested server over SNA and TCP62.
CICS_ESI_ERR_PEM_NOT_ACTIVE
The requested server does not support password expiry management.
176 CICS Transaction Gateway: Programming Reference

CICS_ESI_ERR_PASSWORD_INVALID
The password is invalid.
CICS_ESI_ERR_PASSWORD_REJECTED
The new password does not confirm to the standards defined for the
external security manager.
CICS_ESI_ERR_USERID_INVALID
The userid is not known to the external security manager.
CICS_ESI_ERR_SECURITY_ERROR
An error has been detected by the external security manager. The
most likely explanation is that the userid has been revoked.
The mapping of actual return code values to the symbolic names is contained
in the \include\cics_esi.h file for CICS Transaction Gateway
for Windows and in the /include/cics_esi.h file for CICS
Transaction Gateway for UNIX operating systems. COBOL users can find it in
the \copybook\cicsesi.cbl file.
CICS_SetDefaultSecurity
CICS_SetDefaultSecurity UserId
Password
System
ESI functions
Purpose: The CICS_SetDefaultSecurity function allows a client application
to specify a default userid and password to be used for ECI and EPI requests
passed to the server.
The userid, and the password, can be set to nulls, that is, binary zeroes. In
this case the default userid and password are unset, so that CICS Transaction
Gateway acts as if no userid and password has been set.
The userid, and the password, can also be set to spaces. However, this is valid
only if Usedfltuser=yes is specified in the CICS connection definition. In this
case CICS uses its default userid. Refer to the documentation for your CICS
server for more information on the Usedfltuser specification.
The client application is responsible for verifying the userid and password.
Note that the userid and password, if required, may be obtained from any one
of several places. The assumption is that the CICS Transaction Gateway uses
the following search order:
1. Either the ECI parameter block for the ECI or the terminal specific values
set by the CICS_EpiSetSecurity function.
2. The server specific values set by the CICS_SetDefaultSecurity function.
Chapter 4. C and COBOL 177

ESI functions
3. Defaults, for example the Windows userid, from the CICS Transaction
Gateway’s pop up window, and so on
Parameters:
UserId
Password
System
A pointer to a null-terminated string that specifies the userid
to be set. If the userid is shorter than
CICS_ESI_USERID_MAX characters, it must be padded with
nulls to a length of CICS_ESI_USERID_MAX+1.
The ESI uses this parameter only for input.
A pointer to a null-terminated string that specifies the
password to be set for the specified userid. If the password is
shorter than CICS_ESI_PASSWORD_MAX characters, it must
be padded with nulls to a length of
CICS_ESI_PASSWORD_MAX+1.
The ESI uses this parameter only for input.
A pointer to a null-terminated string that specifies the name of
the server for which the password and userid are to be set. If
the name is shorter than CICS_ESI_SYSTEM_MAX characters,
it must be padded with nulls to a length of
CICS_ESI_SYSTEM_MAX+1.
If the string is all nulls, the default server is selected.
The ESI uses this parameter only for input.
Return codes:
CICS_ESI_NO_ERROR
The function completed successfully.
CICS_ESI_ERR_CALL_FROM_CALLBACK
The function was invoked from a callback routine.
CICS_ESI_ERR_SYSTEM_ERROR
An internal system error occurred.
CICS_ESI_ERR_NO_CICS
The CICS Transaction Gateway is unavailable, or the specified server
is unavailable.
178 CICS Transaction Gateway: Programming Reference

ESI functions
CICS_ESI_ERR_UNKNOWN_SERVER
The requested server could not be located. Only servers returned by
the CICS_EciListSystems and CICS_EpiListSystems functions are
acceptable.
CICS_ESI_ERR_USERID_INVALID
The length of the userid exceeds CICS_ESI_USERID_MAX.
CICS_ESI_ERR_PASSWORD_INVALID
The length of the password exceeds CICS_ESI_PASSWORD_MAX.
The mapping of actual return code values to the symbolic names is contained
in the \include\cics_esi.h file for CICS Transaction Gateway
for Windows and in the /include/cics_esi.h file for CICS
Transaction Gateway for UNIX operating systems. COBOL users can find it in
the \copybook\cicsesi.cbl file.
Chapter 4. C and COBOL 179

ESI functions
180 CICS Transaction Gateway: Programming Reference

Appendix A. COM Global Constants
Constants are provided in the type libraries for the Client daemon COM
libraries. The libraries are in CCLIECI.DLL and CCLIEPI.DLL.
If you are using Visual Basic, you can look at the definitions in the type
libraries by using Visual Basic Object viewer or another type library viewer.
If you are using VBScript, you cannot access the enumerations defined in the
type library; use the numeric values provided here.
The exception code constants are listed in Appendix D, “COM Error Code
References” on page 191.
© Copyright IBM Corp. 1989, 2002 181

182 CICS Transaction Gateway: Programming Reference

Appendix B. COM EPI Specific Constants
Synchronization Types
CclEPI States
CclSession States
CclTerminal States
Table 2. Synchronization types
VB Enumeration Value Description
cclSync 0 Synchronous call type
cclDsync 1 Deferred synchronous call type
Table 3. CclEPI States
VB Enumeration Value Description
cclEPIActive 0 EPI initialized OK
cclDiscon 1 EPI Terminated
cclEPIError 2 EPI failed to initialize, handle exception
for more information
Table 4. CclSession States
VB Enumeration Value Description
cclSessionIdle 0 Idle, client needs to initiate transaction
cclSessionServer 1 Waiting for server
ccISessionClient 2 Waiting for Client daemon to respond
ccISessionDiscon 3 Disconnected
ccISessionError 4 Session Error, handle exception for more
information
Table 5. CclTerminal States
VB Enumeration Value Description
cclInit 0 Terminal defined but not installed
© Copyright IBM Corp. 1989, 2002 183

CclTerminal ATI States
Table 5. CclTerminal States (continued)
VB Enumeration Value Description
cclActive 1 Terminal connected (not used)
cclIdle 2 Idle, Client daemon needs to initiate
transaction
cclServer 3 Waiting for server
cclClient 4 Waiting for client to respond
cclDiscon 5 Disconnected
cclError 6 Terminal error, handle exception for more
information
Table 6. CclTerminal ATI states
VB Enumeration Value Description
cclATIEnabled 0 ATIs are allowed
cclATIDisabled 1 ATIs are not allowed
CclTerminal EndTermReasons
CclTerminal Signon Types
Table 7. CclTerminal ATI states
VB Enumeration Value Description
cclSignoff 0 Disconnect request or user has signed off
the terminal
cclShutdown 1 The CICS server has been shut down
cclOutOfService 2 The terminal has been switched to out of
use
cclUnknown 3 An unknown situation as occurred
cclFailed 4 The terminal failed to disconnect
cclNotDiscon 5 The terminal is not disconnected
Table 8. CclTerminal Signon Types
VB Enumeration Value Description
cclSignonCapable 0 Terminal supports signon transaction
184 CICS Transaction Gateway: Programming Reference

CclScreen AID key codes
Table 8. CclTerminal Signon Types (continued)
VB Enumeration Value Description
cclSignonIncapable 1 Terminal does not support signon
transaction
cclSignonUnknown 2 Terminal signon capability is unknown
Table 9. CclScreen AID key codes
VB Enumeration Value Description
cclEnter 0 Enter key
cclClear 1 Clear key
cclPA1 2 Program Attention key 1
cclPA2 3 Program Attention key 2
cclPA3 4 Program Attention key 3
cclPF1 5 Program Function key 1
cclPF2 6 Program Function key 2
cclPF3 7 Program Function key 3
cclPF4 8 Program Function key 4
cclPF5 9 Program Function key 5
cclPF6 10 Program Function key 6
cclPF7 11 Program Function key 7
cclPF8 12 Program Function key 8
cclPF9 13 Program Function key 9
cclPF10 14 Program Function key 10
cclPF11 15 Program Function key 11
cclPF12 16 Program Function key 12
cclPF13 17 Program Function key 13
cclPF14 18 Program Function key 14
cclPF15 19 Program Function key 15
cclPF16 20 Program Function key 16
cclPF17 21 Program Function key 17
cclPF18 22 Program Function key 18
cclPF19 23 Program Function key 19
cclPF20 24 Program Function key 20
Appendix B. COM EPI Specific Constants 185

Table 9. CclScreen AID key codes (continued)
VB Enumeration Value Description
cclPF21 25 Program Function key 21
cclPF22 26 Program Function key 22
cclPF23 27 Program Function key 23
cclPF24 28 Program Function key 24
CclField Protected State Attributes
Table 10. CclField Protected state attributes
VB Enumeration Value Description
cclProtect 0 Protected Field (cannot be modified)
cclUnprotect 1 Unprotected (input) field
CclField Numeric Attributes
Table 11. CclField Numeric Attributes
VB Enumeration Value Description
cclAlphanumeric 0 Alphanumeric input field
cclNnumeric 1 Numeric input field
CclField Intensity Attributes
Table 12. CclField Intensity attributes
VB Enumeration Value Description
cclNormal 0 Normal display
cclIntense 1 Intensified display
cclDark 2 Non-display field
CclField Modified Attributes
Table 13. CclField Modified Attributes
VB Enumeration Value Description
cclUnmodified 0 Field has not been changed
cclModified 1 Field has been changed
186 CICS Transaction Gateway: Programming Reference

CclField Highlight Attributes
Table 14. CclField Highlight attributes
VB Enumeration Value Description
cclHltDefault 0 Default field text highlighting
cclHltNormal 1 Field text highlight as specified by 3270
base attribute
cclHltBlink 2 Blinking text
cclHltReverse 3 Reverse video text
cclHltUnderscore 4 Underscored text
cclHltIntense 5 High intensity text
CclField Transparency Attributes
CclField Color Attributes
Table 15. CclField Transparency attributes
VB Enumeration Value Description
cclTrnDefault 0 Default (opaque) field background
cclTrnOr 1 Transparent field background (OR)
cclTrnXor 2 Transparent field background (XOR)
cclTrnOpaque 3 Opaque field background
Table 16. CclField Color attributes
VB Enumeration Value Description
cclDefaultColor 0
cclBlue 1
cclRed 2
cclPink 3
cclGreen 4
cclCyan 5
cclYellow 6
cclNeutral 7
cclBlack 8
Appendix B. COM EPI Specific Constants 187

Table 16. CclField Color attributes (continued)
VB Enumeration Value Description
cclDarkBlue 9
cclOrange 10
cclPurple 11
cclPaleGreen 12
cclPaleCyan 13
cclGray 14
cclWhite 15
188 CICS Transaction Gateway: Programming Reference

Appendix C. ECI Constants
Synchronization Types
Flow status types
Connection Status Codes
Table 17. Synchronization types
VB Enumeration Value Description
cclSync 0 Synchronous call type
cclDsync 1 Deferred synchronous call type
Table 18. Flow status types
VB Enumeration Value Description
cclInactive 0 Flow is inactive
cclLink 1 Flow is currently making a link call
cclBackout 2 Flow is currently backing out a UOW
cclCommit 3 Flow is currently committing a UOW
cclStatus 4 Flow is requesting status
cclChanged 5 Flow is requesting a status change
cclCancel 6 Flow is requesting a status cancel
Table 19. Connection status code
VB Enumeration Value Description
cclUnknown 0 The CICS server status is unknown
cclAvailable 1 The CICS server status is available
cclUnavailable 2 The CICS server status is unavailable
© Copyright IBM Corp. 1989, 2002 189

190 CICS Transaction Gateway: Programming Reference

Appendix D. COM Error Code References
Enumeration Value Description ECI EPI
cclNoError 0 No error occurred Yes Yes
cclBufferOverflow 1 Attempted to increase a CclBuf
object which isn’t Extensible
Yes
cclMultipleInstance 2 Attempted to create more than one
ECI object
Yes
cclActiveFlow 3 Current Flow is still active, you
cannot use this flow until it is
inactive
Yes
cclActiveUOW 4 Current UOW is still active, you
need to backout or commit.
cclSyncType 5 Incorrect synchronisation type for
method call.
cclDataLength 9 CommArea > 32768 Bytes or
inbound 3270 data stream too large
for Terminal Buffer size.
cclNoCICS 10 The Client daemon is unavailable,
or the server implementation is
unavailable, or a logical unit of
work was to be begun, but the
CICS server specified is not
available. No resources have been
updated
cclCICSDied 11 A logical unit of work was to be
begun or continued, but the CICS
server was no longer available. If
this is a link call with an active
UOW, the changes are backed out.
If This was a UOW Commit or the
application cannot determine
whether the changes have been
committed or backed out, and
must log this condition to aid
future manual recovery
Yes
Yes Yes
Yes Yes
Yes Yes
cclNoReply 12 There was no outstanding reply Yes
cclTransaction 13 ECI Program Abended Yes
cclSystemError 14 Unknown internal error occurred Yes Yes
© Copyright IBM Corp. 1989, 2002 191
Yes

Enumeration Value Description ECI EPI
cclResource 15 The server implementation or the
Client daemon did not have
enough resources to complete the
request e.g. insufficient SNA
sessions.
Yes Yes
cclMaxUOWs 16 A new logical unit of work was
being created, but the application
already has as many outstanding
logical units of work as the
configuration will support.
cclUnknownServer 17 The requested server could not be
located
cclSecurity 18 You did not supply a valid
combination of user ID and
password, though the server
expects it.
cclMaxServers 19 You attempted to start requests to
more servers than your
configuration allows. You should
consult the documentation for
your Client daemon or server to
see how to control the number of
servers you can use.
cclMaxRequests 20 There were not enough
communication resources to satisfy
the request. You should consult the
documentation for your CICS
Transaction Gateway Client
daemon or server to see how to
control communication resources
cclRolledBack 21 An attempt was made to commit a
logical unit of work, but the server
was unable to commit the changes,
and backed them out instead
Yes
Yes Yes
Yes Yes
Yes Yes
Yes Yes
cclParameter 22 Incorrect parameter supplied Yes Yes
cclInvalidState 23 The Object is not in the correct
state to invoke the method, e.g.
terminal object still in server state
and an attempt to send data is
made.
Yes Yes
ccltransId 24 Null transid supplied or returned
for a pseudo conversational
transaction
192 CICS Transaction Gateway: Programming Reference
Yes
Yes

Enumeration Value Description ECI EPI
cclInitEPI 25 No EPI object or EPI failed to
initialize correctly
Yes
cclConnect 26 Unexpected error trying to add the
terminal
Yes
cclDataStream 27 Unsupported Data Stream Yes
cclInvalidMap 28 Map definition and Screen do not
match
Yes
cclClass 29 Unknown internal Class error
occurred.
Yes Yes
cclStartTranFailure 30 Transaction failed to start Yes
cclTimeout 31 Timeout occurred before response
from Server
Yes Yes
cclNoPassword 32 The object’s password is null. Yes Yes
cclNoUserid 33 The object’s userid is null Yes Yes
cclNullNewPassword 34 The provided password is null Yes Yes
cclPemNotSupported 35 The CICS Server doesn’t support
the Password Expiry Management
facilities. The method cannot be
used
Yes Yes
cclPemNotActive 36 Password Expiry Management is
not active
Yes Yes
cclPasswordExpired 37 The password has expired. No
information has been returned
Yes Yes
cclPasswordInvalid 38 The password is invalid. Yes Yes
cclPasswordRejected 39 Change password failed because
the password doesn’t conform to
standards defined
Yes Yes
cclUseridInvalid 40 The userid is unknown Yes Yes
cclInvalidTermid 41 Invalid Terminal ID Yes
cclInvalidModelId 42 Invalid Model/Type Yes
cclnot3270 43 Not a 3270 device Yes
cclinvalidCCSId 44 Invalid CCSid Yes
cclServerBusy 45 CICS server is busy Yes
cclSignonNotPoss 46 The server does not allow the
terminal to be installed as signon
capable.
Yes
Appendix D. COM Error Code References 193

194 CICS Transaction Gateway: Programming Reference

Appendix E. Java encodings
This appendix lists the supported Java encodings. A canonical name is
converted to the corresponding CCSid so that a CICS server can determine in
which codepage a datastream can be located.
Notes:
1. Your CICS server must support EPI Version 2 for the encodings to be
implemented.
2. Check your CICS Server documentation to find out which CCSids your
server supports.
Canonical name Description CCSid
Cp1252 Windows Latin-1 5348
ISO8859_1 ISO 8859-1, Latin alphabet No. 1 819
UTF8 Eight-bit Unicode Transformation format 1208
ASCII American Standard Code for Information
Interchange
437
Big5 Big 5, Traditional Chinese 950
Cp037 USA, Canada (Bilingual, French), Netherlands,
Portugal, Brazil, Australia
37
Cp273 IBM Austria, Germany 273
Cp277 IBM Denmark, Norway 277
Cp278 IBM Finland, Sweden 278
Cp280 IBM Italy 280
Cp284 IBM Catalan/Spain, Spanish Latin America 284
Cp285 IBM United Kingdom, Ireland 285
Cp297 IBM France 297
Cp420 IBM Arabic 420
Cp424 IBM Hebrew 424
Cp437 MS-DOS United States, Australia, New Zealand,
South Africa
437
Cp500 EBCDIC 500V1 500
Cp838 IBM Thailand extended SBCS 9030
Cp850 MS-DOS Latin-1 850
Cp852 MS-DOS Latin-2 852
© Copyright IBM Corp. 1989, 2002 195

Java encodings
Canonical name Description CCSid
Cp855 IBM Cyrillic 855
Cp856 IBM Hebrew 856
Cp857 IBM Turkish 857
Cp858 Variant of Cp850 with Euro character 858
Cp862 PC Hebrew 862
Cp864 PC Arabic 864
Cp865 MS-DOS Nordic 865
Cp866 MS-DOS Russian 866
Cp868 MS-DOS Pakistan 868
Cp869 IBM Modern Greek 869
Cp870 IBM Multilingual Latin-2 870
Cp871 IBM Iceland 871
Cp874 IBM Thai 9066
Cp875 IBM Greek 875
Cp918 IBM Pakistan (Urdu) 918
Cp921 IBM Latvia, Lithuania (AIX, DOS) 921
Cp922 IBM Estonia (AIX, DOS) 922
Cp923 IBM Latin-9 923
Cp930 Japanese Katakana-Kanji mixed with 4370 UDC,
superset of 5026
930
Cp933 Korean Mixed with 1880 UDC, superset of 5029 933
Cp935 Simplified Chinese Host mixed with 1880 UDC,
superset of 5031
935
Cp937 Traditional Chinese Host mixed with 6204 UDC,
superset of 5033
937
Cp939 Japanese Latin Kanji mixed with 4370 UDC, superset
of 5035
939
Cp942 IBM OS/2 Japanese, superset of Cp932 942
Cp942C Variant of Cp942 942
Cp943 IBM OS/2 Japanese, superset of Cp932 and Shift-JIS 943
Cp943C Variant of Cp943 943
Cp948 OS/2 Chinese (Taiwan) superset of 938 948
Cp949 PC Korean 949
Cp949C Variant of Cp949 949
196 CICS Transaction Gateway: Programming Reference

Java encodings
Canonical name Description CCSid
Cp950 PC Chinese (Hong Kong, Taiwan) 950
Cp964 AIX Chinese (Taiwan) 964
Cp970 AIX Korean 970
Cp1006 IBM AIX Pakistan (Urdu) 1006
Cp1025 IBM Multilingual Cyrillic: Bulgaria, Bosnia,
Herzegovinia, Macedonia (FYR)
1025
Cp1026 IBM Latin-5, Turkey 1026
Cp1097 IBM Iran (Farsi)/Persian 1097
Cp1098 IBM Iran (Farsi)/Persian 1098
Cp1112 IBM Latvia, Lithuania 1112
Cp1122 IBM Estonia 1122
Cp1123 IBM Ukraine 1123
Cp1124 IBM AIX Ukraine 1124
Cp1140 Variant of Cp037 with Euro character 1140
Cp1141 Variant of Cp273 with Euro character 1141
Cp1142 Variant of Cp277 with Euro character 1142
Cp1143 Variant of Cp278 with Euro character 1143
Cp1144 Variant of Cp280 with Euro character 1144
Cp1145 Variant of Cp284 with Euro character 1145
Cp1146 Variant of Cp285 with Euro character 1146
Cp1147 Variant of Cp297 with Euro character 1147
Cp1148 Variant of Cp500 with Euro character 1148
Cp1149 Variant of Cp871 with Euro character 1149
Cp1250 Windows Eastern European 5346
Cp1251 Windows Cyrillic 5347
Cp1253 Windows Greek 5349
Cp1254 Windows Turkish 5350
Cp1255 Windows Hebrew 5351
Cp1256 Windows Arabic 5352
Cp1257 Windows Baltic 5353
Cp1258 Windows Vietnamese 5354
Cp1381 IBM OS/2, DOS People’s Republic of China (PRC) 1381
Cp1383 IBM AIX, People’s Republic of China (PRC) 1383
Appendix E. Java encodings 197

Java encodings
Canonical name Description CCSid
EUC_CN GB2312, EUC encoding, Simplified Chinese 1383
EUC_JP JIS X 0201, 0208, 0212, EUC encoding, Japanese 954
EUC_KR KS C 5601, EUC encoding, Korean 970
GBK GBK, Simplified Chinese 1386
ISO8859_2 ISO 8859-2, Latin alphabet No. 2 912
ISO8859_5 ISO 8859-5, Latin/Cyrillic alphabet 915
ISO8859_6 ISO 8859-6, Latin/Arabic alphabet 1089
ISO8859_7 ISO 8859-7, Latin/Greek alphabet 813
ISO8859_8 ISO 8859-8, Latin/Hebrew alphabet 916
ISO8859_9 ISO 8859-9, Latin alphabet No. 5 920
ISO8859_15_FDIS ISO 8859-15, Latin alphabet No. 9 923
JIS0201 JIS X 0201, Japanese 5050
JIS0208 JIS X 0208, Japanese 5050
JIS0212 JIS X 0212, Japanese 5050
EUC_TW CNS 11643 (Plane 1-3), EUC encoding, Traditional
Chinese
964
MS932 Windows Japanese 943
MS936 Windows Simplified Chinese 1386
MS949 Windows Korean 1363
198 CICS Transaction Gateway: Programming Reference

Appendix F. C++ Exception Objects
All exception objects provide the following information
v Class Name
v Method Name
v Exception Code
v Exception Text
v Abend Code (ECI Only)
v Origin Point
The Class name can contain a trailing ’I’ for example CclFlowI which implies
it is a internally contained class for the well known class, e.g. CclFlowI is
contained by CclFlow. if an internal class is reported the method reported
may be an internal method, not an external one.
The Origin Point is a unique value which defines the exact point within the
class library where the exception was generated. These are mainly useful for
service.
The more important items of information are the Exception Code, Exception
Text and Abend Code (ECI only). The following is a Summary of these
Exception Codes and Text and whether they are relevent to ECI or EPI or
both.
Table 20. Exception codes
Enumeration Text Description ECI EPI
Ccl::noError no error No error occurred Yes Yes
Ccl::bufferOverflow buffer overflow Attempted to increase
a CclBuf object which
isn’t Extensible
Yes
Ccl::multipleInstance multiple instance Attempted to create
more than one ECI
object
Ccl::activeFlow flow is active Current Flow is still
active, you cannot use
this flow until it is
inactive
Ccl::activeUOW UOW is active Current UOW is still
active, you need to
backout or commit.
© Copyright IBM Corp. 1989, 2002 199
Yes
Yes
Yes

Table 20. Exception codes (continued)
Enumeration Text Description ECI EPI
Ccl::syncType sync error Incorrect
synchronisation type
for method call.
Yes Yes
Ccl::threadCreate thread create error Internal thread
creation error
Ccl::threadWait thread wait error Internal thread wait
error
Ccl::threadKill thread kill error Internal thread kill
error
Ccl::dataLength data length invalid CommArea > 32768
Bytes or inbound 3270
data stream too large
for Terminal Buffer
size.
Ccl::noCICS no CICS The Gateway is
unavailable, or the
server implementation
is unavailable, or a
logical unit of work
was to be begun, but
the CICS server
specified is not
available. No resources
have been updated
Ccl::CICSDied CICS died A logical unit of work
was to be begun or
continued, but the
CICS server was no
longer available. If this
is a link call with an
active UOW, the
changes are backed
out. If this was a UOW
Commit or Backout,
the application cannot
determine whether the
changes have been
committed or backed
out, and must log this
condition to aid future
manual recovery.
Ccl::noReply no reply There was no
outstanding reply
200 CICS Transaction Gateway: Programming Reference
Yes Yes
Yes
Yes
Yes Yes
Yes Yes
Yes
Yes

Table 20. Exception codes (continued)
Enumeration Text Description ECI EPI
Ccl::transaction transaction abend ECI Program Abended Yes
Ccl::systemError system error Unknown internal
error occurred
Yes Yes
Ccl::resource resource shortage The server
implementation or the
Gateway did not have
enough resources to
complete the request
e.g. insufficient SNA
sessions.
Yes Yes
Ccl::maxUOWs exceeded max UOWs A new logical unit of
work was being
created, but the
application already has
as many outstanding
logical units of work
as the configuration
will support.
Ccl::unknownServer unknown server The requested server
could not be located
Ccl::security security error You did not supply a
valid combination of
user ID and password,
though the server
expects it.
Ccl::maxServers exceeded max servers You attempted to start
requests to more
servers than your
configuration allows.
You should consult the
documentation for
your Gateway or
server to see how to
control the number of
servers you can use.
Yes
Yes Yes
Yes Yes
Yes Yes
Appendix F. C++ Exception Objects 201

Table 20. Exception codes (continued)
Enumeration Text Description ECI EPI
Ccl::maxRequests exceeded max requests There were not enough
communication
resources to satisfy the
request. You should
consult the
documentation for
your Gateway or
server to see how to
control communication
resources
Yes Yes
Ccl::rolledBack rolled back An attempt was made
to commit a logical
unit of work, but the
server was unable to
commit the changes,
and backed them out
instead
Ccl::parameter parameter error Incorrect parameter
supplied
Ccl::invalidState invalid object state The Object is not in
the correct state to
invoke the method,
e.g. terminal object still
in server state and an
attempt to send data is
made.
Ccl::transId invalid transaction Null transid supplied
or returned for a
pseudo conversational
transaction
Ccl::initEPI EPI not initialised EPI has failed to
initialize correctly or
EPI object is missing
Ccl::connect connection failed Unexpected error
trying to add the
terminal
Ccl::dataStream 3270 datastream error Unsupported Data
Stream
Ccl::invalidMap map/screen mismatch Map definition and
Screen do not match
Ccl::cclClass CICS class error Unknown internal
Class error occurred.
202 CICS Transaction Gateway: Programming Reference
Yes
Yes Yes
Yes Yes
Yes
Yes
Yes
Yes
Yes
Yes Yes

Table 20. Exception codes (continued)
Enumeration Text Description ECI EPI
Ccl::startTranFailure Start Transaction Transaction failed to
Yes
Failure
start
Ccl::timeout Timeout Occurred Timeout occurred
before response from
Server
Yes Yes
Ccl::noPassword Password is Null The object’s password
is null.
Ccl::noUserid Userid is Null The object’s userid is
null
Ccl::nullNewPassword A NULL new
password was
supplied
Ccl::pemNotSupported PEM is not supported
on the server
Ccl::pemNotActive PEM is not active on
the server
The provided
password is null
The CICS Server
doesn’t support the
Password Expiry
Management facilities.
The method cannot be
used
Password Expiry
Management is not
active
Ccl::passwordExpired Password has expired The password has
expired. No
information has been
returned
Ccl::passwordInvalid Password is invalid The password is
invalid.
Ccl::passwordRejected New password was
rejected
Change password
failed because the
password doesn’t
conform to standards
defined
Yes Yes
Yes Yes
Yes Yes
Yes Yes
Yes Yes
Yes Yes
Yes Yes
Yes Yes
Ccl::useridInvalid Userid unknown at
server
The userid is unknown Yes Yes
Ccl:invalidTermid Termid is invalid The terminal ID is
invalid
Yes
Ccl:invalidModelid Modelid is invalid Invalid Model/Device
Type
Yes
Ccl:not3270 Not a 3270 device Not a 3270 device Yes
Appendix F. C++ Exception Objects 203

Table 20. Exception codes (continued)
Enumeration Text Description ECI EPI
Ccl:invalidCCSid Codepage (CCSid
value) is invalid
Invalid CCSid Yes
Ccl:serverBusy Server is too busy CICS server is busy Yes
Ccl:signonNotPossible Signon Capable The server does not
Yes
terminal is not possible allow the terminal to
be installed as signon
capable.
204 CICS Transaction Gateway: Programming Reference

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The product library and related literature
This chapter lists books on the CICS Transaction Gateway, and related topics.
It also discusses how you can view the online library supplied with the
product.
It consists of the following topics:
“CICS Transaction Gateway books” Read this for a list of all books provided
with the CICS Transaction Gateway.
“Sample configuration documents” on
page 206
Read this for information about a series of
PDF documents that provide step-by-step
guidance on configuring the CICS
Transaction Gateway.
“Redbooks ” on page 207 Read this for details of other publications
that contain examples of client/server
configurations.
“Other Useful Books” on page 207 Read this for details of other relevant
publications.
“Obtaining books from IBM” on page 209 Read this for information on downloading
books and ordering hardcopy versions.
CICS Transaction Gateway books
v CICS Transaction Gateway: Windows Administration, SC34-6190
This book describes the administration of the CICS Transaction Gateway for
Windows.
v CICS Transaction Gateway: UNIX Administration, SC34-6139
This book describes the administration of the CICS Transaction Gateway for
UNIX operating systems.
v CICS Transaction Gateway: z/OS Administration, SC34-6191
This book describes the administration of the CICS Transaction Gateway for
z/OS.
v CICS Transaction Gateway: Gateway Messages
This online book lists and explains the error messages that can be generated
by CICS Transaction Gateway.
You cannot order this book.
v CICS Transaction Gateway: Programming Reference, SC34-6140
© Copyright IBM Corp. 1989, 2002 205

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The CICS Transaction Gateway
This book provides information on the APIs of the programming languages
supported by the CICS Transaction Gateway.
There are also additional HTML pages that contain JAVA programming
reference information.
v CICS Transaction Gateway: Programming Guide, SC34-6141
This introduction to programming for the CICS Transaction Gateway
provides the information that you need to allow non-CICS applications to
use CICS facilities in a client/server environment.
Sample configuration documents
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. .
The following scenarios are currently covered:
v Configuring CICS Transaction Gateway for Windows for Microsoft SNA
Server
v Configuring CICS Transaction Gateway for Windows for eNetwork Personal
Communications
v Configuring CICS Transaction Gateway for Windows for TCP62
v Configuring CICS Transaction Gateway for AIX for IBM eNetwork
Communications Server
v Configuring CICS Transaction Gateway for Windows for Communications
Server
v Configuring CICS Transaction Gateway for Terminal Servlets using
WebSphere ® Application Server for Windows
v Client security configuration
v Configuring CICS Transaction Gateway for WebSphere 4.01 using J2EE
v Configuring CICS Transaction Gateway 4.02 for WebSphere Application
Server on z/OS using J2EE
As more sample configuration documents become available, you can
download them from our Web site at:
www.ibm.com/software/ts/cics/
and follow the Download link.
206 CICS Transaction Gateway: Programming Reference

Redbooks
Other Useful Books
The following International Technical Support Organization (ITSO) Redbook
publication contains many examples of client/server configurations:
v CICS Transaction Gateway V3.1 The WebSphere Connector for CICS, SG24-6133
This book supersedes the following book:
v Revealed! CICS Transaction Gateway with more CICS Clients Unmasked,
SG24-5277.
v Java Connectors for CICS: Featuring the J2EE Connector Architecture, SG24-6401.
This book provides information on developing J2EE applications.
See also:
v Securing Web Access to CICS, SG24–5756.
v Workload Management for Web Access to CICS, SG24–6118.
You can obtain ITSO Redbooks from a number of sources. For the latest
information, see:
www.ibm.com/redbooks/
CICS Transaction Server publications
Other publications
CICS interproduct communication
The following books describe the intercommunication facilities of the CICS
server products:
CICS Family: Interproduct Communication, SC34-6030
Transaction Server for Windows NT: Intercommunication, SC33-1882
CICS Transaction Server for z/OS: Intercommunication Guide, SC34-6005
CICS Transaction Server for VSE/ESA : Intercommunication Guide, SC33-1665
CICS for OS/400 ® : Intercommunication, SC33-1388
TXSeries: CICS Intercommunication Guide, SC09-3900
CICS for OS/2: Intercommunication, SC33-1583
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:
Transaction Server for Windows NT: Problem Determination, GC33-1883
CICS Transaction Server for z/OS ® Problem Determination Guide, SC34-6002
The product library and related literature 207

Other publications
CICS Transaction Server for VSE/ESA Problem Determination Guide,
GC33-1663
CICS for OS/400 ® : Problem Determination, SC33-1384
TXSeries: CICS Problem Determination Guide, SC33-1565.
You can find information on CICS products at the following Web site:
www.ibm.com/software/ts/cics/
Microsoft ® Windows Family publications
The following book provides introductory material about the Windows Family
of operating systems:
v Windows NT System Guide
APPC-related publications
The following books are concerned with products providing APPC support:
IBM products
IBM Communications Server for Windows NT and Windows 2000:
Communications Server for Windows: Quick Beginnings, GC31-8424
IBM Communications Server for AIX for AIX:
IBM Communications Server for AIX: Quick Beginnings, GC31-8583
IBM Communications Server for AIX: General Information, GC31-8584
IBM Communications Server for AIX: Administration, SC31-8586
IBM Communications Server for AIX: Administration Command Reference,
SC31-8587
IBM eNetwork Personal Communications:
IBM Personal Communications for Windows NT: Quick Beginnings,
GC31-8679-02
IBM Personal Communications: Administrator’s Reference, SC31-8840
Microsoft products
Microsoft SNA Server Installation Guide
Microsoft SNA Server Administration Guide
Microsoft SNA Server Reference
Systems Network Architecture (SNA)
SNA Formats, GA27-3136
Systems Network Architecture Technical Overview, GC30-3073
208 CICS Transaction Gateway: Programming Reference

TCP62–related publications
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
GC31–7073
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074
Obtaining books from IBM
For information on books you can download, visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link.
You can order hardcopy books:
v Through your IBM representative or the IBM branch office serving your
locality.
v By calling 1-800-879-2755 in the United States.
v From the Web site at:
www.ibm.com/shop/publications/order
Other publications
The product library and related literature 209

210 CICS Transaction Gateway: Programming Reference

|
|
|
|
|
|
|
|
|
|
Accessibility
The English version of the CICS Transaction Gateway has been tested for
accessibility on the Windows operating system. The product is accessible.
Documentation
Download the CICS Information Center for an html version of the
documentation. Go to this Web page
www.ibm.com/software/ts/cics/
and follow the Library link.
© Copyright IBM Corp. 1989, 2002 211

212 CICS Transaction Gateway: Programming Reference

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.
A
abend. The termination of a task, job, or
subsystem because of an error condition that
recovery facilities cannot resolve.
APAR. (Authorized program analysis report.) A
report on the basis of which IBM supplies a fix
of a temporary corrective nature to elements of
function SYSMODs. APAR fixes are called
″corrective″ service because they are installed to
cure problems currently being experienced by an
installation. The APAR fix is usually in the form
of either a modification to a load module or an
update to card-image data. It is intended as a
temporary arrangement until a preventive service
(PTF) is issued to fix the problem permanently.
This PTF supersedes the APAR fix, and indeed
specifies this relationship on its ++VER
statement.
API. Application programming interface.
APING. A command used to verify an APPC
link.
APPC. Advanced program-to-program
communication. 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.
applet. A Java program that is downloaded to,
and executed on, a Web browser or network
computer. See also servlet.
applid. In CICS, a system initialization and
terminal control parameter that identifies the
CICS system to other remote systems.
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 facility that enables terminal
definitions to be created automatically in a CICS
server on request. The definition is deleted when
the client terminal is logged off.
automatic transaction initiation (ATI). The
process whereby a transaction request made
internally within a CICS system or network leads
to the scheduling of the transaction. An ATI
request from a CICS Transaction Gateway can
cause the initiation of a transaction in a CICS
server system.
B
beans. See JavaBeans .
BIND. 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.
C
CA. See certification authority.
CEDA. A CICS transaction that defines
resources online.
© Copyright IBM Corp. 1989, 2002 213

Glossary
certification authority. In computer security, an
organization that issues certificates. The
certification 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 External Call Interface (EXCI). An
application programming interface that enables a
program running on Z/OS, such as CICS
Transaction Gateway, to call a program running
in a CICS region. The programs can transfer data
between each other using a communication area.
Compare with External Call Interface (ECI).
CICS Gateway for Java. In CICS Universal
Clients Version 2, an interface between a Java
program and CICS that allows a Java-enabled
browser to dynamically download a Java Applet
and transparently access CICS data. This has
been replaced by the CICS Transaction Gateway.
CICS on open systems. A term used to refer
generically to the products: CICS for HP-UX,
CICS for Sun Solaris, TXSeries for AIX,
TXSeries for HP-UX, and TXSeries for Solaris.
CICS on System/390 ® . A term used to refer
generically to the products CICS Transaction
Server for z/OS , CICS for MVS/ESA ,CICS
Transaction Server for z/OS, CICS Transaction
Server for VSE/ESA, and CICS/VSE ® .
cicscli. A command that starts and stops the
Client daemon, checks the availability of servers,
and sets other options.
cicsprnt. A command that allows you to define
a printer terminal on the Client daemon
workstation. The command enables CICS
applications running on the server to direct
output to the client-attached printer.
cicsterm. A command that provides 3270
emulation and enables connection to a CICS
region.
214 CICS Transaction Gateway: Programming Reference
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. An environment variable that tells
the JVM and other Java applications where to
find the class libraries, including user-defined
class libraries.
Client API. On distributed platforms running
non-Java applications, the interface between the
Client application and the Client daemon.
client application. A user application, written in
a supported programming language other than
Java, that communicates directly with the Client
daemon.
Client daemon. The Client daemon (process
cclclnt) exists only on distributed platforms. 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. A distributed application design
model, in which the client sends a request to its
partner, the server, which executes the request
and returns the results to the client. This design
model is associated typically with cooperative
processing.
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. File CICSCOL.INI used by
the CICS Transaction Gateway to customize the
3270 screen color attributes on client
workstations.
COMMAREA. A communication area that is
used for passing data both between programs
within a transaction and between transactions.

Common Object Request Broker Architecture
(CORBA). An industry standard for an interface
definition language that enables different object
request brokers to interoperate.
configuration file. The file CTG.INI containing
information telling CICS Transaction Gateway
about the CICS servers that it can connect to, and
the communication protocols to use.
configuration tool. A graphical user interface
that allows you to configure the CICS
Transaction Gateway.
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.
control table. In CICS, a storage area used to
describe or define the configuration or operation
of the system.
conversation. The communication between a
CICS Transaction Gateway and a CICS server. In
APPC, a connection between two transaction
programs over an LU-LU session that allows
them to communicate with each other while
processing a transaction. See also session.
conversation security. In APPC, a process that
allows validation of a user ID or group ID and
password before establishing a connection.
cooperative processing. A subset of distributed
processing, in which at least the user interface
(presentation) aspect of the application runs on a
programmable workstation.
CORBA. See Common Object Request Broker
Architecture.
ctgstart. A command that starts the gateway
daemon.
D
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.
Glossary
dependent LU. A logical unit (LU) that can
receive, but not send a BIND, and which
supports only single sessions. See BIND.
digital certificate. A form of personal
identification that can be verified electronically.
Only the certificate owner who holds the
corresponding private key can present a
certificate for authentication through a Web
browser session. Anyone can verify that the
certificate is valid by using a readily available
public key.
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. A link that enables
an application program running on one CICS
system to link to another application program
running in another CICS system.
Glossary 215

Glossary
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.
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.
E
EBCDIC. Extended binary-coded decimal
interchange code. A coded character set of 256
8-bit characters developed for the representation
of textual data.
ECI. See external call interface.
emulator, 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. In the CICS Transaction
Gateway the terminal emulation function allows
client workstations to run CICS transactions that
use 3270 data flows.
216 CICS Transaction Gateway: Programming Reference
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.
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 10–megabit or 100–megabit
baseband 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 CICS External Call Interface.
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.
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.
F
firewall. A configuration of software that
prevents unauthorized traffic between a trusted
network and an untrusted network.

G
gateway. A device that connects two dissimilar
LANs, or that connects a LAN to a wide area
network (WAN), midrange computer, or
mainframe computer. A gateway device has its
own processor and memory and may perform
protocol conversion. A gateway handles multiple
communication sessions simultaneously.
gateway classes. The interface for Java Client
applications to connect to the Gateway daemon.
The Gateway classes, which are supplied with
the CICS Transaction Gateway, must be in the
classpath for Java Client applications to run.
gateway daemon. Used only in remote mode,
the Gateway daemon listens on protocols defined
in CTG.INI for gateway requests from remote
Java client applications. It issues these requests to
the Client daemon on distributed platforms, and
directly to CICS over the EXCI on z/OS. The
Gateway daemon runs the protocol listener
threads, the worker threads and the connection
manager threads. It uses the GATEWAY section
of CTG.INI (and on z/OS the ctgenvvar script)
for its configuration.
H
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 in an internet.
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
domain name of a host.
HTTP. In the Internet suite of protocols, the
protocol that is used to transfer and display
hypertext and XML documents.
HTTPS. A TCP/IP protocol that World Wide
Web servers and Web browsers use to transfer
and display documents secured by SSL.
I
iKeyman. A tool supplied with the Gateway for
maintaining digital certificates for SSLight and
JSSE.
independent LU. A logical unit (LU) that can
both send and receive a BIND, and which
supports single, parallel, and multiple sessions.
See BIND.
internet. A collection of networks
interconnected by a set of routers that allow
them to function as a single, large network.
Contrast with Internet.
Internet. The internet administered by the
Internet Architecture Board (IAB), consisting of
large national backbone networks and many
regional and campus networks all over the
world. The Internet uses the Internet suite of
protocols.
Internet address. See IP address.
Glossary
Internet Architecture Board. The technical body
that oversees the development of the internet
suite of protocols known as TCP/IP.
Internet Packet Exchange (IPX). In Novell
NetWare LANs, a communication protocol that
sends data packets to requested destinations.
Internet Protocol (IP). In TCP/IP, a protocol
that routes data from its source to its destination
in an Internet environment.
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.
intranet. A private network that integrates
Internet standards and applications (such as Web
browsers) with an organization’s existing
Glossary 217

Glossary
computer networking infrastructure. Compare
with Internet and internet.
IP. Internet Protocol.
IPX. Internet Packet Exchange.
J
J2EE. (Java 2 Platform, Enterprise Edition.) 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.
Java. An object-oriented programming language
for portable interpretive code that supports
interaction among remote objects.
JavaBeans. A platform-independent, software
component technology for building reusable Java
components called beans. Once built, these beans
can be made available for use by other software
engineers or they can be used in Java
applications. Also, using JavaBeans, software
engineers can manipulate and assemble beans in
a graphical drag-and-drop development
environment.
Java client application. A Java application,
servlet or applet that communicates with the
Gateway classes.
Java development kit (JDK). A software
package that can be used to write, compile,
debug, and run Java applets and applications.
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 Secure Socket Extension (JSSE). An
implementation of SSL, written in Java, and
supported by CICS Transaction Gateway.
218 CICS Transaction Gateway: Programming Reference
Java Virtual Machine (JVM). A software
implementation of a processor that runs
compiled Java code (applets and applications).
JDK. See Java development kit (JDK).
JNI. See Java Native Interface (JNI).
JSSE. See Java Secure Socket Extension (JSSE).
JVM. See Java Virtual Machine (JVM).
K
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. The default keyboard mapping file for
the CICS Transaction Gateway is CICSKEY.INI.
KeyRing or KeyStore. In computer security, a
file that contains public keys, private keys,
trusted roots, and certificates.
L
LAN. See local area network.
local area network (LAN). A network of
workstations, or terminals, or both, where all the
connected systems are relatively near to each
other. See wide area network.
local mode. Describes a Java Client application
using the Gateway local protocol. The Gateway
daemon is not used in local mode; on distributed
platforms, the Gateway classes interface directly
with the Client daemon API, and with the EXCI
on z/OS. See remote mode.
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.
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.
LU-LU session type 6.2. In SNA, a type of
session for communication between peer
systems. Synonymous with APPC protocol.
LU 6.2. See APPC.
M
MAC. Medium access control.
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.
N
name server. In TCP/IP, synonym for Domain
Name Server In Internet communications, the
host that translates host names into their
respective internet addresses when requested by
the hosts on the network A physical device, and
its associated software, that enables a processor
or controller to be connected to a network.
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.
O
object. In object-oriented programming, a
concrete realization of a class that consists of
data and the operations associated with that
data.
object request broker (ORB). Software that
serves as an intermediary by transparently
enabling objects to exchange requests and
responses.
OO. Object-oriented.
P
Glossary
pacing. A technique by which a receiving
station controls the rate of transmission of a
sending station to prevent overrun.
packet internet groper (PING). In Internet
communications, a program used in TCP/IP
networks to test the ability to reach destinations
Glossary 219

Glossary
by sending the destinations an Internet Control
Message Protocol (ICMP) echo request and
waiting for a reply.
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. Packet internet groper. The command
that sends an ICMP Echo Request packet to a
gateway, router, or host with the expectation of
receiving 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. Primary logical unit. 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.
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 (LU) that contains the primary half-session
for a particular LU-LU session. Contrast with
secondary logical unit. See also logical unit.
Note: A particular logical unit may contain
primary and secondary half-sessions for
different active LU-LU sessions.
protocol boundary. The signals and rules
governing interactions between two components
within a node.
220 CICS Transaction Gateway: Programming Reference
R
RACF ® . Resource Access Control Facility. An
IBM licensed program that provides access
control by identifying users to the system;
verifying users of the system; authorizing access
to protected resources; logging detected,
unauthorized attempts to enter the system; and
logging detected accesses to protected resources.
region. A physical instance of a CICS server.
remote mode. Describes a Java Client
application using a Gateway network protocol to
connect to the Gateway daemon. See local mode.
remote procedure call (RPC). Remote procedure
calls are analogous to the standard procedure
calls used in modern programming, providing
modularity and reducing code size. The main
difference between standard procedure calls and
remote procedure calls is that in a remote
procedure call, the called procedure is being
executed by a different process than the caller. To
the calling procedure, a remote procedure call
looks the same as a call to a local procedure.
When a program makes a remote procedure call
to a remote application, the procedure’s
parameters are automatically bundled into a
request message, which is then sent to the
remote program or system.
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.
RU. Request unit. Response unit.

RPC. See remote procedure call.
S
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.
servlet. A Java servlets program that run on a
Web server machine, unlike Java applets, which
are downloaded to a Web browser. Java servlets
have become popular as a replacement for CGI
(Common Gateway Interface) programs.
session. In SNA, a logical connection between
two network addressable units (NAUs) that can
be activated, tailored to provide various
protocols, and deactivated as requested. The
session activation request and response can
determine options for such things as rate and
concurrency of data exchange, control of
contention and error recovery, and characteristics
of the data stream. Sessions compete for network
resources, such as links within the path control
network. For routing purposes, each session is
identified by the network or local addresses of
the session partners. See LU-LU session, LU-LU
session type.
session limit. In SNA, the maximum number of
concurrently active LU-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.
signon capable terminal. A signon capable
terminal allows signon transactions, either
CICS-supplied (CESN) or user-written, to be run.
Contrast with signon incapable terminal.
SIT (system initialization table). A table
containing parameters used to start a CICS
control region.
SNA gateway. A gateway that handles multiple
APPC communication sessions simultaneously.
See gateway.
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.
SSL. See Secure Sockets Layer (SSL).
Glossary
SSLight. An implementation of SSL, written in
Java, and supported by CICS Transaction
Gateway.
System Management Interface Tool (SMIT). In
the AIX operating system, a set of menu-driven
services that facilitate the performance of system
tasks such as installation, management,
configuration, and diagnosis.
standard error. In many workstation-based
operating systems, the output stream to which
error messages or diagnostic messages are sent.
subnet. In TCP/IP, a part of a network that is
identified by a portion of the Internet address.
Synonym for subnetwork.
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.
Systems Network Architecture (SNA). The
description of the logical structure, formats,
protocols, and operational sequences for
Glossary 221

Glossary
transmitting information units through, and
controlling the configuration and operation of,
networks.
System SSL. An implementation of SSL,
supported by CICS Transaction Gateway on
z/OS. Written in native code, it supports
hardware encryption technology available to
z/OS, and can be used only for SSL servers on
that operating system.
T
Taskguide. A function of the configuration tool
that provides step-by-step guidance to
configuring your CICS Transaction Gateway. .
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. Transmission Control Protocol/Internet
Protocol.
TCP/IP address. An address that uniquely
identifies a machine on a network. A machine
can have several threads of execution running at
the same time; a TCP/IP port uniquely identifies
a particular thread.
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.
Terminal Servlet. A Java program that allows
you to use a Web browser as an emulator for a
3270 CICS application running on any CICS
server.
thread. A stream of computer instructions that
is in control of a process. A multithread process
begins with one stream of instructions (one
thread) and may later create other instruction
streams to perform tasks.
222 CICS Transaction Gateway: Programming Reference
token ring. A network with a ring topology that
passes tokens from one attaching device to
another; for example, the IBM Token-Ring
network.
trace. A record of data that provides a history of
events that occurred in a system. The process of
recording the sequence in which the statements
in a program are executed and, optionally, are
the values of the program variables used in the
statements.
transaction program. A program that uses the
APPC application program interface (API) to
communicate with a partner application program
in the same node or at a partner node.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A set of communications protocols
that support peer-to-peer connectivity functions
for both local and wide area networks. TCP/IP
can be used for client/server links between the
Client daemon and, for example, CICS for
OS/2 ® , CICS for Windows NT.
type 2.0 node. An SNA node that attaches to a
subarea network as a peripheral node and
provides full 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.
U
URL. (Uniform Resource Locator.) 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.
user session. Any APPC session other than a
SNASVCMG session.

V
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.
W
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.
Glossary
Glossary 223

Glossary
224 CICS Transaction Gateway: Programming Reference

Index
Special characters
(parameter)
in changed 57
vii
A
abendCode
in CclException class 66
in CclFlow class 74
in Public methods 66, 74
AbendCode
in Methods
in Flow COM Class 23
accessibility 211
active
in state 65
in State 65
activeFlow
in CclConn class 56
in CclFlow class 73
in CclUOW class 95
activeUOW
in CclConn class 56
in CclUOW class 95
AID
in CclScreen class 81
in Enumerations 81
alphanumeric
in BaseType 72
in inputType 69
alterSecurity
in CclConn class 56
in CclTerminal class 88
in Public methods 56, 88
AlterSecurity
in Methods
in Connect COM Class 4
in Terminal COM Class 36
alterSecurity (parameter)
in alterSecurity 56
AppendString
in Methods
in Buffer COM Class 2
appendText
in CclField class 67, 68
in Public methods 67, 68
AppendText
in Methods
in Field COM Class 17
array (parameter)
in SetData 3
assign
in CclBuf class 51
in Public methods 51
async
in CclSession constructor 84
in Sync 49
ATIState
in CclTerminal class 94
in Enumerations 94
ATIState parameter
CICS_EpiATIState function 161
attachTran (parameter)
in CclConn constructor 56
in TranDetails 9
attribute (parameter)
in setBaseAttribute 70
in setExtAttribute 70
Attribute (parameter)
in SetBaseAttribute 21
in SetExtAttribute 21
Attributes parameter
CICS_EpiAddExTerminal function 150
available
in ServerStatus 60
B
backgroundColor
in CclField class 68
in Public methods 68
BackgroundColor
in Methods
in Field COM Class 18
backout
in CallType 77
in CclUOW class 95
in Public methods 95
Backout
in Poll 24
BackOut
in Methods
in UOW COM Class 45
baseAttribute
in CclField class 68
in Public methods 68
BaseAttribute
in Methods
in Field COM Class 18
© Copyright IBM Corp. 1989, 2002 225

BaseInts
in CclField class 71
in Enumerations 71
BaseMDT
in CclField class 72
in Enumerations 72
BaseProt
in CclField class 72
in Enumerations 72
BaseType
in CclField class 72
in Enumerations 72
black
in Color 72
blinkHlt
in Highlight 72
blue
in Color 72
books 205
CICS Transaction Gateway 205
Bool
in Ccl class 49
in Enumerations 49
Buffer
in AppendString 2
in Buffer COM Class 1
in Link 7
in Poll 24
in String 4
buffer (parameter)
in CclBuf 51
in operator!= 54
in operator+= 53
in operator= 53
in operator== 54
Buffer COM class
Methods
AppendString 2
Data 2
ExtractString 2
InsertString 2
Length 3
Overlay 3
SetData 3
SetLength 3
SetString 3
String 4
C
callback routine
ECI 107, 111, 116, 120
EPI 146, 150
callType
in CclFlow class 74
in Public methods 74
226 CICS Transaction Gateway: Programming Reference
CallType
in CclFlow class 76
in Enumerations 76
in Methods
in Flow COM Class 23
callTypeText
in CclFlow class 74
in Public methods 74
CallTypeText
in Methods
in Flow COM Class 23
cancel
in CallType 77
in CclConn class 57
in Public methods 57
Cancel
in Methods
in Connect COM Class 5
in Poll 24
Ccal Screen.fieldbyPosition method
in Field COM class 17
Ccl class
Bool 49
Sync 49
Ccl.Field
in FieldByName 27
Ccl.Screen
in Send 41
cclActive
in State 16, 34
cclAlphanumeric
in InputType 20
cclATIDisabled
in QueryATI 40
in SetATI 42
cclATIEnabled
in QueryATI 40
in SetATI 42
cclAvailable
in ServerStatus 8
CclBuf
in CclBuf class 50, 51
in CclBuf constructors 50, 51
CclBuf class
assign 51
CclBuf 50, 51
cut 51
dataArea 52
dataAreaLength 52
dataAreaOwner 52
DataAreaOwner 55
dataAreaType 52
DataAreaType 55
dataLength 52
insert 53

CclBuf class (continued)
listState 53
operator!= 54
operator+= 53, 54
operator= 53
operator== 54
replace 54
setDataLength 55
CclBuf constructors
CclBuf 50, 51
in CclBuf class 50
cclClient
in State 35
CclConn class
alterSecurity 56
cancel 57
change password 57
changed 57
link 57
listState 58
makeSecurityDefault 58
password 58, 59
serverName 59
serverStatus 59
ServerStatus 60
serverStatusText 60
status 59
userId 60
verifyPassword 60
CclConn constructor
in CclConn class 56
cclDark
in Intensity 20
cclDiscon
in State 16, 35
cclDSync
in SetSyncType 24, 25, 34
CclECI class
exCode 61
exCodeText 61
handleException 62
instance 62
listState 62
serverCount 62
serverDesc 62
serverName 63
CclECI constructor (protected)
in CclECI class 61
CclEPI class
diagnose 63
exCode 63
exCodeText 64
handleException 64
serverCount 64
serverDesc 64
CclEPI class (continued)
serverName 65
state 65
State 65
terminate 65
CclEPI constructor
in CclEPI class 63
cclError
in State 16, 35
CclException class
abendCode 66
className 66
diagnose 66
exCode 67
exCodeText 67
exObject 67
methodName 67
CclField class
appendText 67, 68
backgroundColor 68
baseAttribute 68
BaseInts 71
BaseMDT 72
BaseProt 72
BaseType 72
Color 72
column 68
dataTag 68
foregroundColor 69
highlight 69
Highlight 72
inputProt 69
inputType 69
intensity 69
length 69
position 70
resetDataTag 70
row 70
setBaseAttribute 70
setExtAttribute 70
setText 71
text 71
textLength 71
transparency 71
Transparency 72
CclFlow
in CclFlow class 73
in CclFlow constructor 73
CclFlow class
abendCode 74
callType 74
CallType 76
callTypeText 74
CclFlow 73
connection 74
Index 227

CclFlow class (continued)
diagnose 74
flowId 74
forceReset 74
handleReply 75
listState 75
poll 75
setTimeout 76
syncType 76
timeout 76
uow 76
wait 76
CclFlow constructor
CclFlow 73
in CclFlow class 73
cclIntense
in Intensity 20
CclMap class
exCode 77
exCodeText 78
field 78
namedField 78
validate 78
CclMap constructor
in CclMap class 77
cclModified
in DataTag 18
cclNoError
in ExCode 15
cclNormal
in Intensity 20
cclNumeric
in InputType 20
CclOSecTime
in Ccl SecAttr interface 32
cclProtect
in InputProt 19
CclScreen class
AID 81
cursorCol 79
cursorRow 79
depth 80
field 80
fieldCount 80
mapName 80
mapSetName 80
setAID 81
setCursor 81
width 81
CclSecAttr 82
cclServer
in State 35
CclSession class
diagnose 84
handleReply 84
228 CICS Transaction Gateway: Programming Reference
CclSession class (continued)
state 85
State 85
terminal 85
transID 85
CclSession constructor
in CclSession class 84
cclSync
in SetSyncType 24, 25, 34
cclSystemError
in ExCode 15
CclTerminal class
alterSecurity 88
ATIState 94
CCSid 88
changePassword 88
diagnose 88
disconnect 88, 89
discReason 89
EndTerminalReason 95
exCode 89
exCodeText 89
install 90
makeSecurityDefault 90
netName 90
password 90
poll 90
queryATI 91
readTimeout 91
receiveATI 91
screen 92
send 92
serverName 93
setATI 92
signonCapability 93
signonType 94
state 93
State 94
termID 93
transID 93
userId 93
verifyPassword 94
CclTerminal constructor
in CclTerminal class 86
cclUnavailable
in ServerStatus 8
cclUnknown
in ServerStatus 8
cclUnknownServer
in ExCode 15
cclUnmodified
in DataTag 18
in ResetDataTag 21
cclUnprotect
in InputProt 19

CclUOW class
backout 95
commit 96
forceReset 96
listState 96
uowId 96
CclUOW constructor
in CclUOW class 95
CCSid
in CclTerminal class 88
in Public methods 88
CCSId
in Methods
in Terminal COM class 36
CCSid (parameter)
in CclTerminal constructor 87
in SetTermDefns 42
change password
in CclConn class 57
in Public methods 57
changed
in CallType 77
in CclConn class 57
in Public methods 57
in ServerStatus 8
in ServerStatusText 8
Changed
in Cancel 5
in Changed 5
in Details 6
in Methods
in Connect COM Class 5
in Poll 24
changePassword
in CclTerminal class 88
in Public methods 88
ChangePassword
in Methods
in Connect COM Class 5
in Terminal COM Class 36
CICS Transaction Gateway initialization file
in CclTerminal constructor 86
in serverCount 62, 64
in serverDesc 64
in serverName 65
CICS_ChangePassword function
definition 174
CICS_ECI_DESCRIPTION_MAX 129
CICS_ECI_SYSTEM_MAX 129
CICS_EciListSystems function 129
ECI_ERR_INVALID_DATA _LENGTH 130
ECI_ERR_MORE_SYSTEMS 130
ECI_ERR_NO_CICS 130
ECI_ERR_NO_SYSTEMS 130
ECI_ERR_SYSTEM_ERROR 130
CICS_EciListSystems function (continued)
ECI_NO_ERROR 130
CICS_EciSystem_t data structure
definition 129
use 129
CICS_EPI_ADD_TERM event
definition 166
CICS_EPI_ATI_HOLD 161
CICS_EPI_ATI_ON 161
CICS_EPI_ATI_QUERY 162
CICS_EPI_DESCRIPTION_MAX, 131
CICS_EPI_DEVTYPE_MAX 146, 150
CICS_EPI_END_FAILED 169
CICS_EPI_END_OUTSERVICE 169
CICS_EPI_END_SHUTDOWN 169
CICS_EPI_END_SIGNOFF 169
CICS_EPI_END_UNKNOWN 169
CICS_EPI_ERR_ABENDED return code
CICS_EpiReply function 161
CICS_EPI_ERR_ADDTYPE_INVALID return code
CICS_EpiAddExTerminal function 151
CICS_EPI_ERR_ALREADY_INSTALLED return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 147
CICS_EPI_ERR_ATI_ACTIVE return code
CICS_EpiStartTran function 158, 159
CICS_EPI_ERR_ATI_STATE return code
CICS_EpiATIState function 162
CICS_EPI_ERR_BAD_INDEX return code
CICS_EpiATIState function 162
CICS_EpiDelTerminal function 154
CICS_EpiGetEvent function 164
CICS_EpiGetSysError function 166
CICS_EpiInquireSystem function 153
CICS_EpiPurgeTerminal function 155
CICS_EpiReply function 160
CICS_EpiSenseCode function 163
CICS_EpiSetSecurity function 156
CICS_EpiStartTran function 159
CICS_EPI_ERR_CCSID_INVALID return code
CICS_EpiAddExTerminal function 152
CICS_EPI_ERR_FAILED return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EpiATIState function 162
CICS_EpiDelTerminal function 154
CICS_EpiGetEvent function 164
CICS_EpiGetSysError function 165, 166
CICS_EpiInitialize function 142
CICS_EpiInquireSystem function 153
CICS_EpiListSystems function 143
CICS_EpiPurgeTerminal function 155
CICS_EpiReply function 160
CICS_EpiSenseCode function 163
CICS_EpiStartTran function 159
Index 229

CICS_EPI_ERR_FAILED return code (continued)
CICS_EpiTerminate function 142
CICS_EPI_ERR_IN_CALLBACK return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EpiATIState function 162
CICS_EpiDelTerminal function 154
CICS_EpiGetEvent function 165
CICS_EpiInquireSystem function 153
CICS_EpiListSystems function 144
CICS_EpiPurgeTerminal function 155
CICS_EpiReply function 160
CICS_EpiSenseCode function 163
CICS_EpiSetSecurity function 156
CICS_EpiStartTran function 159
CICS_EpiTerminate function 142
CICS_EPI_ERR_IS_INIT return code
CICS_EpiInitialize function 142
CICS_EPI_ERR_MAX_SESSIONS return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 148
CICS_EpiStartTran function 159
CICS_EPI_ERR_MAX_SYSTEMS return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 148
CICS_EPI_ERR_MODEL_INVALID return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 147
CICS_EPI_ERR_MORE_DATA return code
CICS_EpiGetEvent function 164
CICS_EPI_ERR_MORE_EVENTS return code
CICS_EpiGetEvent function 164
CICS_EPI_ERR_MORE_SYSTEMS return code
CICS_EpiListSystems function 143
CICS_EPI_ERR_NO_CONVERSE return code
CICS_EpiReply function 160
CICS_EPI_ERR_NO_DATA return code
CICS_EpiReply function 160
CICS_EpiStartTran function 159
CICS_EPI_ERR_NO_EVENT return code
CICS_EpiGetEvent function 164
CICS_EPI_ERR_NO_SYSTEMS return code
CICS_EpiListSystems function 144
CICS_EPI_ERR_NOT_3270_DEVICE return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 147
CICS_EPI_ERR_NOT_INIT return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EpiATIState function 162
CICS_EpiDelTerminal function 154
CICS_EpiGetEvent function 164
CICS_EpiGetSysError function 166
CICS_EpiInquireSystem function 153
CICS_EpiListSystems function 144
230 CICS Transaction Gateway: Programming Reference
CICS_EPI_ERR_NOT_INIT return code (continued)
CICS_EpiPurgeTerminal function 155
CICS_EpiReply function 160
CICS_EpiSenseCode function 163
CICS_EpiSetSecurity function 156
CICS_EpiStartTran function 159
CICS_EpiTerminate function 142
CICS_EPI_ERR_NULL_PARM return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EpiGetEvent function 164
CICS_EpiGetSysError function 166
CICS_EpiInquireSystem function 153
CICS_EpiListSystems function 144
CICS_EPI_ERR_NULL_PASSWORD return code
CICS_EpiSetSecurity function 156
CICS_EPI_ERR_NULL_USERID return code
CICS_EpiSetSecurity function 157
CICS_EPI_ERR_PASSWORD_INVALID return code
CICS_EpiAddExTerminal function 151
CICS_EpiSetSecurity function 157
CICS_EPI_ERR_RESOURCE _SHORTAGE return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 148
CICS_EpiStartTran function 159
CICS_EPI_ERR_RESPONSE_TIMEOUT return code
CICS_EpiAddExTerminal function 151
CICS_EPI_ERR_SECURITY return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EPI_ERR_SENSE_CODE return code
CICS_EpiSenseCode function 163
CICS_EPI_ERR_SERVER_BUSY return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 147
CICS_EPI_ERR_SERVER_DOWN return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EpiReply function 160
CICS_EpiStartTran function 159
CICS_EPI_ERR_SIGNON_NOT_POSS return code
CICS_EpiAddExTerminal function 151
CICS_EPI_ERR_SIGNONCAP_INVALID return code
CICS_EpiAddExTerminal function 151
CICS_EPI_ERR_SYSTEM return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EPI_ERR_SYSTEM_ERROR return code
CICS_EpiSetSecurity function 156
CICS_EPI_ERR_TERMID_INVALID return code
CICS_EpiAddExTerminal function 151
CICS_EpiAddTerminal function 147
CICS_EPI_ERR_TRAN_ACTIVE return code
CICS_EpiDelTerminal function 154

CICS_EPI_ERR_TTI_ACTIVE return code
CICS_EpiStartTran function 159
CICS_EpiTerminate function 142
CICS_EPI_ERR_USERID_INVALID return code
CICS_EpiAddExTerminal function 151
CICS_EpiSetSecurity function 157
CICS_EPI_ERR_VERSION return code
CICS_EpiAddExTerminal function 152
CICS_EpiInitialize function 142
CICS_EpiPurgeTerminal function 155
CICS_EpiSetSecurity function 156
CICS_EPI_ERR_WAIT return code
CICS_EpiGetEvent function 164
CICS_EPI_ERROR_MAX 137
CICS_EPI_EVENT_CONVERSE event
definition 167
use 160, 167
CICS_EPI_EVENT_END_TERM event
definition 169
use 135, 153, 154
CICS_EPI_EVENT_END_TRAN event
definition 167
use 135, 157, 158
CICS_EPI_EVENT_SEND event
definition 166
CICS_EPI_EVENT_START_ATI event
definition 168
use 159
CICS_EPI_NETNAME_MAX 133, 145, 149
CICS_EPI_NORMAL return code
CICS_EpiAddExTerminal function 152
CICS_EpiAddTerminal function 148
CICS_EpiATIState function 162
CICS_EpiDelTerminal function 154
CICS_EpiGetEvent function 165
CICS_EpiGetSysError function 166
CICS_EpiInitialize function 142
CICS_EpiInquireSystem function 153
CICS_EpiListSystems function 144
CICS_EpiPurgeTerminal function 155
CICS_EpiReply function 161
CICS_EpiSenseCode function 163
CICS_EpiSetSecurity function 157
CICS_EpiStartTran function 159
CICS_EpiTerminate function 142
CICS_EPI_NOWAIT 164
CICS_EPI_NULL_PARAM return code
CICS_EpiATIState function 162
CICS_EPI_READTIMEOUT _EXPIRED 168
CICS_EPI_SENSE_OPCHECK 162
CICS_EPI_SENSE_REJECT 163
CICS_EPI_SYSTEM_MAX 131, 145, 148
CICS_EPI_TERM_INDEX_NONE 163
CICS_EPI_TRAN_NO_ERROR 168
CICS_EPI_TRAN_NOT_STARTED 168
CICS_EPI_TRAN_STATE _UNKNOWN 168
CICS_EPI_TRANSID_MAX 135, 158
CICS_EPI_VERSION return code
CICS_EpiGetSysError function 166
CICS_EpiSenseCode function 163
CICS_EPI_VERSION_200 141
CICS_EPI_WAIT 164
CICS_EpiAddExTerminal function
definition 148
use 131, 132, 133
CICS_EpiAddTerminal function
definition 144
use 131, 133, 157, 161, 165
CICS_EpiATIState function
definition 161
CICS_EpiAttributes_t data structure
definition 132
CICS_EpiDelTerminal function
definition 153
use 142, 154, 169
CICS_EpiDetails_t data structure
definition 133
use 144, 146, 148, 150
CICS_EpiEventData_t data structure
definition 135
use 164
CICS_EpiGetEvent function
definition 163
use 135, 136, 154, 159
CICS_EpiGetSysError function
definition 165
use 137
CICS_EpiInitialize function
definition 141
use 142, 143, 165
CICS_EpiInquireSystem function
definition 152
CICS_EpiListSystems function
definition 143
use 131, 165
CICS_EpiPurgeTerminal function
ATI request cancellation 155
definition 154
CICS_EpiReply function
definition 159
use 167
CICS_EpiSenseCode function
definition 162
CICS_EpiSetSecurity function
definition 155
CICS_EpiStartTran function
definition 157
use 158, 167
CICS_EpiSysError_t data structure
definition 136
Index 231

CICS_EpiSysError_t data structure (continued)
use 165
CICS_EpiSystem_t data structure
definition 131
use 143
CICS_EpiTerminate function
definition 142
use 165
CICS_ESI_ERR_CALL_ FROM_CALLBACK return code
CICS_ChangePassword function 175
CICS_SetDefaultSecurity function 178
CICS_VerifyPassword function 173
CICS_ESI_ERR_CICS_DIED return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 173
CICS_ESI_ERR_MAX_SESSIONS return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 173
CICS_ESI_ERR_MAX_SYSTEMS return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 173
CICS_ESI_ERR_NO_CICS return code
CICS_ChangePassword function 176
CICS_SetDefaultSecurity function 178
CICS_VerifyPassword function 173
CICS_ESI_ERR_NO_SESSIONS return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 173
CICS_ESI_ERR_NULL_ NEW_PASSWORD return code
CICS_ChangePassword function 176
CICS_ESI_ERR_NULL_ OLD_PASSWORD return code
CICS_ChangePassword function 176
CICS_ESI_ERR_NULL_PASSWORD return code
CICS_VerifyPassword function 174
CICS_ESI_ERR_NULL_USERID return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 173
CICS_ESI_ERR_PASSWORD _REJECTED return code
CICS_ChangePassword function 177
CICS_ESI_ERR_PASSWORD_EXPIRED return code
CICS_VerifyPassword function 174
CICS_ESI_ERR_PASSWORD_INVALID return code
CICS_ChangePassword function 177
CICS_SetDefaultSecurity function 179
CICS_VerifyPassword function 174
CICS_ESI_ERR_PEM_NOT _SUPPORTED return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 174
CICS_ESI_ERR_PEM_NOT_ACTIVE return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 174
CICS_ESI_ERR_RESOURCE_SHORTAGE return code
CICS_ChangePassword function 176
CICS_VerifyPassword function 173
232 CICS Transaction Gateway: Programming Reference
CICS_ESI_ERR_SECURITY_ERROR return code
CICS_ChangePassword function 177
CICS_VerifyPassword function 174
CICS_ESI_ERR_SYSTEM_ERROR return code
CICS_ChangePassword function 176
CICS_SetDefaultSecurity function 178
CICS_VerifyPassword function 173
CICS_ESI_ERR_UNKNOWN_SERVER return code
CICS_ChangePassword function 176
CICS_SetDefaultSecurity function 179
CICS_VerifyPassword function 173
CICS_ESI_ERR_USERID_INVALID return code
CICS_ChangePassword function 177
CICS_SetDefaultSecurity function 179
CICS_VerifyPassword function 174
CICS_ESI_NO_ERROR return code
CICS_ChangePassword function 175
CICS_SetDefaultSecurity function 178
CICS_VerifyPassword function 173
CICS_EsiDate_t data structure
definition 170
CICS_EsiDetails_t data structure
definition 170
CICS_EsiTime_t data structure
definition 170
CICS_ExternalCall 129
CICS_SetDefaultSecurity function
definition 177
CICS_VerifyPassword function
definition 171
CicsClientStatus 128
CicsServerStatus 128
className
in CclException class 66
in Public methods 66
clear
in AID 81
client
in send 92
in State 85, 94
code page 102, 109, 121, 125
col
in validate 79
col (parameter)
in setCursor 81
Color
in CclField class 72
in Enumerations 72
colPos (parameter)
in FieldByPosition 29
in SetCursor 30
column
in CclField class 68
in Public methods 68

Column
in Methods
in Field COM Class 18
column (parameter)
in field 78, 80
commarea (parameter)
in handleReply 75
in link 57, 58
in poll 75
commArea (parameter)
in AbendCode 23
in Link 7
in Poll 24
commit
in CallType 77
in CclUOW class 96
in Public methods 96
Commit
in Methods
in UOW COM Class 46
in Poll 24
Connect
in Connect COM Class 4
in Methods
in Terminal COM Class 36
in ServerName 8
in Terminal COM class 35
in UOW COM Class 45
in UserId 10
Connect COM class
Methods
AlterSecurity 4
Cancel 5
Changed 5
ChangePassword 5
Details 6
Link 7
MakeSecurityDefault 7
Password 7
ServerName 8
ServerStatus 8
ServerStatusText 8
Status 8
TranDetails 9
UnpaddedPassword 9
UnpaddedServerName 9
UnpaddedUserid 9
UserId 10
VerifyPassword 10
connection
in CclFlow class 74
in Public methods 74
ConnectionType 128
CreateObject 1, 4, 11, 13, 23, 26, 34, 35, 45
cursorCol
in CclScreen class 79
in Public methods 79
CursorCol
in Methods
in Screen COM Class 28
cursorRow
in CclScreen class 79
in Public methods 79
CursorRow
in Methods
in Screen COM Class 28
cut
in CclBuf class 51
in Public methods 51
cyan
in Color 72
D
dark
in BaseInts 71
in intensity 69
darkBlue
in Color 72
Data
in Methods
in Buffer COM Class 2
data conversion 102, 109, 121, 125
Data parameter
CICS_EpiReply function 160
CICS_EpiStartTran function 158
dataArea
in CclBuf class 52
in Public methods 52
dataArea (parameter)
in assign 51
in CclBuf 50, 51
in insert 53
in replace 54
dataAreaLength
in CclBuf class 52
in Public methods 52
dataAreaOwner
in CclBuf class 52
in Public methods 52
DataAreaOwner
in CclBuf class 55
in Enumerations 55
dataAreaType
in CclBuf class 52
in Public methods 52
DataAreaType
in CclBuf class 55
in Enumerations 55
Index 233

dataLength
in CclBuf class 52
in link 58
in Public methods 52
dataStream
in CclScreen class 79
dataTag
in CclField class 68
in Public methods 68
DataTag
in Methods
in Field COM Class 18
Day
in SecTime COM Class 32
defaultColor
in Color 72
defaultHlt
in Highlight 72
defaultTran
in Transparency 72
depth
in CclScreen class 80
in Public methods 80
in validate 79
Depth
in Methods
in Screen COM Class 28
Description
CICS_EciListSystems 129
Details
in Connect COM class 4
in Methods
in Connect COM Class 6
Details parameter
CICS_ChangePassword function 175
CICS_EpiAddExTerminal function 150
CICS_EpiAddTerminal function 146
CICS_VerifyPassword function 173
Devtype
in Methods
in Terminal COM Class 37
devtype (parameter)
in CclTerminal constructor 86, 87
devType (parameter)
in Connect 36, 37
in SetTermDefns 42
DevType parameter
CICS_EpiAddExTerminal function 149
CICS_EpiAddTerminal function 146
DFHCNV macro 102, 109, 121, 125
diagnose
in CclEPI class 63
in CclException class 66
in CclFlow class 74
in CclSession class 84
234 CICS Transaction Gateway: Programming Reference
diagnose (continued)
in CclTerminal class 88
in Public methods 63, 66, 74, 84, 88
Diagnose
in EPI COM Class 13
in Methods
in EPI COM Class 13
in Flow COM Class 23
in Session COM Class 34
in Terminal COM Class 37
in State 16, 35
disability 211
disabled
in ATIState 94
in queryATI 91
in setATI 92
discon
in state 65
in State 65, 85, 94
disconnect
in CclTerminal class 88, 89
in Public methods 88, 89
Disconnect
in Disconnect 37
in Methods
in Terminal COM Class 37
DisconnectWithPurge
in Methods
in Terminal COM Class 37
discReason
in CclTerminal class 89
in Public methods 89
DiscReason
in DiscReason 38
in Methods
in Terminal COM Class 38
display (parameter)
in ErrorWindow 11, 14
documentation 205
dsync
in CclSession constructor 84
in Sync 49
E
ECI COM class
Methods
ErrorFormat 11
ErrorOffset 11
ErrorWindow 11
ExCode 11
ExCodeText 12
ServerCount 12
ServerDesc 12
ServerName 12
SetErrorFormat 13

ECI parameter block 97
ECI status block 128
eci_abend_code
field in ECI parameter block 97
with ECI_SYNC call type 101
ECI_ASYNC call type
definition 106
ECI_BACKOUT 100, 103, 107, 110
eci_call_type 97
field in ECI parameter block 97
with ECI_ASYNC call type 107
with ECI_GET_REPLY call type 121
with ECI_GET_REPLY_WAIT call type 124
with ECI_GET_SPECIFIC_REPLY call type 125
with ECI_GET_SPECIFIC_REPLY_WAIT call
type 128
with ECI_STATE_ASYNC call type 117
with ECI_STATE_SYNC call type 113
with ECI_SYNC call type 100
eci_callback 107, 116
field in ECI parameter block 98
with ECI_ASYNC call type 111
with ECI_STATE_ASYNC call type 119
ECI_CLIENTSTATE_INAPPLICABLE 129
ECI_CLIENTSTATE_UNKNOWN 129
ECI_CLIENTSTATE_UP 129
eci_commarea
field in ECI parameter block 97
with ECI_ASYNC call type 109
with ECI_GET_REPLY call type 121
with ECI_GET_SPECIFIC_REPLY call type 125
with ECI_STATE_ASYNC call type 117
with ECI_STATE_SYNC call type 113
with ECI_SYNC call type 101
eci_commarea_length
field in ECI parameter block 97
with ECI_ASYNC call type 109
with ECI_GET_REPLY call type 121
with ECI_GET_SPECIFIC_REPLY call type 125
with ECI_STATE_ASYNC call type 117
with ECI_STATE_SYNC call type 114
with ECI_SYNC call type 102
ECI_COMMIT 100, 103, 107, 110
ECI_CONNECTED_NOWHERE 128
ECI_CONNECTED_TO_CLIENT 128
ECI_CONNECTED_TO_SEVER 128
ECI_ERR_ALREADY_ACTIVE 106, 113
ECI_ERR_CALL_FROM _CALLBACK 99, 130
ECI_ERR_CICS_DIED 105, 122, 126
ECI_ERR_INVALID_CALL_TYPE 99
ECI_ERR_INVALID_DATA _LENGTH 105, 112, 116,
120, 122, 126, 130
ECI_ERR_INVALID_DATA_AREA 106, 113, 116, 120,
123, 127
ECI_ERR_INVALID_EXTEND _MODE 105, 113, 116,
120
ECI_ERR_INVALID_VERSION 99
ECI_ERR_LUW_TOKEN 105, 113, 116, 120
ECI_ERR_MAX_SESSIONS 106, 123, 127
ECI_ERR_MAX_SYSTEMS 106, 123, 127
ECI_ERR_MORE_SYSTEMS 130
ECI_ERR_NO_CICS 105, 113, 122, 126, 130
ECI_ERR_NO_REPLY 123, 126
ECI_ERR_NO_SESSIONS 106, 113
ECI_ERR_NO_SYSTEMS 130
ECI_ERR_REQUEST_TIMEOUT 99
ECI_ERR_RESOURCE_SHORTAGE 106, 113, 123, 127
ECI_ERR_RESPONSE_TIMEOUT 99
ECI_ERR_ROLLEDBACK 106, 123, 127
ECI_ERR_SECURITY_ERROR 106, 123, 127
ECI_ERR_SYSTEM_ERROR 99, 130
ECI_ERR_THREAD_CREATE _ERROR 113, 123, 127
ECI_ERR_TRANSACTION _ABEND 105, 123
ECI_ERR_TRANSACTION_ABEND 126
ECI_ERR_UNKNOWN_SERVER 106, 116, 123, 127
eci_extend_mode 100, 101, 105, 107, 109, 112, 113, 114,
115, 117, 119, 121, 125
field in ECI parameter block 98
with ECI_ASYNC call type 109
with ECI_STATE_ASYNC call type 118
with ECI_STATE_SYNC call type 114
with ECI_SYNC call type 102
ECI_EXTENDED 103, 110
ECI_GET_REPLY call type
definition 120
ECI_GET_REPLY_WAIT call type
definition 124
ECI_GET_SPECIFIC_REPLY call type
definition 124
ECI_GET_SPECIFIC_REPLY_WAIT call type
definition 127
eci_luw_token
field in ECI parameter block 98
with ECI_ASYNC call type 110
with ECI_STATE_ASYNC call type 119
with ECI_STATE_SYNC call type 115
with ECI_SYNC call type 103
eci_message_qualifier
field in ECI parameter block 98
with ECI_ASYNC call type 107, 110
with ECI_GET_SPECIFIC_REPLY call type 124, 125
with ECI_STATE_ASYNC call type 117, 118
ECI_NO_ERROR 105, 112, 116, 120, 122, 126, 130
ECI_NO_EXTEND 102, 110
eci_password 100, 104, 108, 112
field in ECI parameter block 97
with ECI_ASYNC call type 108
with ECI_SYNC call type 101
eci_password2 100, 101, 108
Index 235

eci_password2 (continued)
field in ECI parameter block 98
with ECI_ASYNC call type 112
with ECI_SYNC call type 104
eci_program_name
field in ECI parameter block 97
with ECI_ASYNC call type 107
with ECI_SYNC call type 100
ECI_SERVERSTATE_DOWN 128
ECI_SERVERSTATE_UNKNOWN 128
ECI_SERVERSTATE_UP 128
ECI_STATE_ASYNC call type
definition 116
ECI_STATE_CANCEL 113, 114, 115, 117, 118, 119, 121,
125
ECI_STATE_CHANGED 114, 115, 118, 119
ECI_STATE_IMMEDIATE 114, 118
ECI_STATE_SYNC call type
definition 113
ECI_STATUS 128
ECI_SYNC call type
definition 100
eci_sysid
field in ECI parameter block 98
with ECI_ASYNC call type 111
with ECI_GET_REPLY call type 121
with ECI_GET_SPECIFIC_REPLY call type 125
with ECI_STATE_ASYNC call type 119
with ECI_STATE_SYNC call type 115
with ECI_SYNC call type 103
eci_system_name
field in ECI parameter block 98
with ECI_ASYNC call type 111
with ECI_STATE_ASYNC call type 119
with ECI_STATE_SYNC call type 115
with ECI_SYNC call type 104
eci_timeout
field in ECI parameter block 98
with ECI_SYNC call type 102, 109
eci_tpn
field in ECI parameter block 99
with ECI_ASYNC call type 112
with ECI_SYNC call type 104
eci_transid
field in ECI parameter block 97
with ECI_ASYNC call type 108
with ECI_SYNC call type 101
eci_userid 101, 104, 108, 112
field in ECI parameter block 97
with ECI_ASYNC call type 108
with ECI_SYNC call type 100
eci_userid2 100, 101, 108
field in ECI parameter block 98
with ECI_ASYNC call type 112
with ECI_SYNC call type 104
236 CICS Transaction Gateway: Programming Reference
eci_version
field in ECI parameter block 98
with ECI_ASYNC call type 111
with ECI_GET_REPLY call type 122
with ECI_GET_SPECIFIC_REPLY call type 125
with ECI_STATE_ASYNC call type 119
with ECI_STATE_SYNC call type 115
with ECI_SYNC call type 104
ECI_VERSION_1 98, 104, 111, 115, 119, 122, 125
ECI_VERSION_1A 98, 104, 111, 112, 115, 119, 122, 125
enabled
in ATIState 94
in queryATI 91
in setATI 92
EndTerminalReason
in CclTerminal class 95
in Enumerations 95
enter
in AID 81
Enumerations
AID 81
ATIState 94
BaseInts 71
BaseMDT 72
BaseProt 72
BaseType 72
Bool 49
CallType 76
Color 72
DataAreaOwner 55
DataAreaType 55
EndTerminalReason 95
Highlight 72
in Ccl class 49
in CclBuf class 55
in CclConn class 60
in CclEPI class 65
in CclField class 71
in CclFlow class 76
in CclScreen class 81
in CclSession class 85
in CclTerminal class 94
ServerStatus 60
signonType 94
State 65, 85, 94
Sync 49
Transparency 72
EPI
constants 130
data structures 131
events 166
functions 137
in EPI COM Class 13

EPI COM class
Methods
Diagnose 13
ErrorFormat 14
ErrorOffset 14
ErrorWindow 14
ExCode 14
ExCodeText 15
ServerCount 15
ServerDesc 15
ServerName 16
SetErrorFormat 16
State 16
Terminate 17
error
in state 65
in State 66, 85, 94
ErrorFormat
in Methods
in ECI COM Class 11
in EPI COM Class 14
ErrorOffset
in Methods
in ECI COM Class 11
in EPI COM Class 14
ErrorWindow
in Methods
in ECI COM Class 11
in EPI COM Class 14
ESI
constants 169
data structures 170
functions 171
Event parameter
CICS_EpiGetEvent function 164
except (parameter)
in handleException 62, 64
exCode
in CclECI class 61
in CclEPI class 63
in CclException class 67
in CclMap class 77
in CclTerminal class 89
in Public methods 61, 63, 67, 77, 89
ExCode 11, 14
in EPI COM Class 13
in ErrorWindow 11, 14
in Methods
in ECI COM Class 11
in EPI COM Class 14
in Map COM Class 26
in Terminal COM Class 38
in State 16, 35
exCodeText
in CclECI class 61
exCodeText (continued)
in CclEPI class 64
in CclException class 67
in CclMap class 78
in CclTerminal class 89
in Public methods 61, 64, 67, 78, 89
ExCodeText
in ExCode 12
in Methods
in ECI COM Class 12
in EPI COM Class 15
in Terminal COM Class 38
EXEC CICS CONVERSE 167
EXEC CICS RECEIVE 158, 160, 167
EXEC CICS RECEIVE BUFFER 167
EXEC CICS SEND 166
exObject
in CclException class 67
in Public methods 67
ExpiryTime
in SecAttr COM class 31
extensible
in CclBuf 50, 51
in CclBuf class 50
in dataAreaType 52
in DataAreaType 55
in setDataLength 55
external
in dataAreaOwner 52
in DataAreaOwner 55
ExtractString
in Methods
in Buffer COM Class 2
F
failed
in EndTerminalReason 95
false
in ErrorWindow 11, 14
False
in Poll 24, 40
FALSE
in Validate 27
field
in CclMap class 78
in CclScreen class 80
in Public methods 78, 80
Field
in Field COM Class 17
in Screen COM Class 28
Field COM class
Methods
AppendText 17
BackgroundColor 18
BaseAttribute 18
Index 237

Field COM class (continued)
Methods (continued)
Column 18
DataTag 18
ForegroundColor 19
Highlight 19
InputProt 19
InputType 20
Intensity 20
Length 20
Position 20
ResetDataTag 21
Row 21
SetBaseAttribute 21
SetExtAttribute 21
SetText 21
Text 22
TextLength 22
Transparency 22
FieldByIndex
in Methods
in Screen COM Class 29
FieldByName
in Methods
in Map COM Class 27
in Validate 27
FieldByPosition
in Methods
in Screen COM Class 29
fieldCount
in CclScreen class 80
in Public methods 80
FieldCount
in Methods
in Screen COM Class 29
fields
in validate 79
fields (parameter)
in validate 78, 79
fixed
in CclBuf 50, 51
in CclBuf class 50
in dataAreaType 52
in DataAreaType 55
Flow
in Cancel 5
in Changed 5
in Commit 46
in Connect COM Class 4
in Flow COM class 22
in Flow COM Class 22
in Link 7
in SetSyncType 24, 25
in Status 9
238 CICS Transaction Gateway: Programming Reference
flow (parameter)
in backout 95, 96
in BackOut 45
in cancel 57
in Cancel 5
in changed 57
in Changed 5
in commit 96
in Commit 46
in link 57, 58
in Link 7
in status 59
in Status 9
Flow COM class
Methods
AbendCode 23
CallType 23
CallTypeText 23
Diagnose 23
Flowid 24
ForceReset 24
Poll 24
SetSyncType 24
SetTimeout 25
SyncType 25
Timeout 25
Wait 25
flowId
in CclFlow class 74
in Public methods 74
Flowid
in Methods
in Flow COM Class 24
forceReset
in CclFlow class 74
in CclUOW class 96
in Public methods 74, 96
ForceReset
in Methods
in Flow COM Class 24
in UOW COM Class 46
foregroundColor
in CclField class 69
in Public methods 69
ForegroundColor
in Methods
in Field COM Class 19
format (parameter)
in SetErrorFormat 13, 16
G
Gateway initialization file
in Connect 37
in Details 6
in ServerCount 12, 15

Gateway initialization file (continued)
in ServerDesc 15
in ServerName 8, 16, 41
GetDate
in SecTime COM Class 32
glossary of terms and abbreviations 213
gray
in Color 72
green
in Color 72
H
handleException
in CclECI class 62
in CclEPI class 64
in Public methods 62, 64
handleReply
in CclFlow class 75
in CclSession class 84
in Public methods 75, 84
highlight
in CclField class 69
in Public methods 69
Highlight
in CclField class 72
in Enumerations 72
in Methods
in Field COM Class 19
Hours
in SecTime COM Class 32
Hunderdths
in SecTime COM Class 33
I
idle
in send 92
in State 85, 94
in Buffer COM Class 1
in Connect COM Class 4
in ECI COM Class 11
in EPI COM Class 13
in field COM Class 23, 26, 34, 35, 45
inactive
in CallType 76
index (parameter)
in ExCode 15
in field 78, 80
in FieldByIndex 29
in namedField 78
in serverDesc 62, 63, 64
in ServerDesc 12, 15
in serverName 63, 65
in ServerName 12, 13, 16
in validate 78, 79
initEPI
in CclEPI constructor 63
in CclTerminal constructor 86
inputProt
in CclField class 69
in Public methods 69
InputProt
in Methods
in Field COM Class 19
inputType
in CclField class 69
in Public methods 69
InputType
in Methods
in Field COM Class 20
insert
in CclBuf class 53
in Public methods 53
InsertString
in Methods
in Buffer COM Class 2
install
in CclTerminal class 90
in Public methods 90
Install
in Methods
in Terminal COM Class 39
install_path vii
installation
path vii
installation path vii
instance
in CclECI class 62
in Public methods 62
intense
in BaseInts 71
in intensity 69
intenseHlt
in Highlight 72
intensity
in CclField class 69
in Public methods 69
Intensity
in Methods
in Field COM Class 20
internal
in CclBuf 51
in dataAreaOwner 52
in DataAreaOwner 55
invalidMap
in CclMap constructor 77
invalidState
in poll 91
in send 92
Index 239

J
Javadoc 47
K
key (parameter)
in setAID 81
in SetAID 30
L
labels
in validate 79
LastVerifiedTime
in SecAttr COM class 31
len
in validate 79
length
in CclField class 69
in Public methods 69
Length
in Methods
in Buffer COM Class 3
in Field COM Class 20
length (parameter)
in appendText 68
in assign 51
in CclBuf 50, 51
in cut 51, 52
in ExtractString 2
in insert 53
in replace 54
in setDataLength 55
in SetLength 3
in setText 71
link
in CallType 77
in CclConn class 57
in Public methods 57
in SetSyncType 25
Link
in Details 6
in Methods
in Connect COM Class 7
in Poll 24
in UOW COM class 45
List parameter 130
CICS_EciListSystems 129
CICS_EpiListSystems function 143
listState
in CclBuf class 53
in CclConn class 58
in CclECI class 62
in CclFlow class 75
in CclUOW class 96
in Public methods 53, 58, 62, 75, 96
240 CICS Transaction Gateway: Programming Reference
M
makeSecurityDefault
in CclConn class 58
in CclTerminal class 90
in Public methods 58, 90
MakeSecurityDefault
in Methods
in Connect COM Class 7
in Terminal COM Class 39
Map
in Map COM Class 26
map (parameter)
in validate 78, 79
Map COM class
Methods
ExCode 26
FieldByName 27
Validate 27
mapName
in CclScreen class 80
in Public methods 80
MapName
in Methods
in Screen COM Class 29
mapname (parameter)
in Validate 27
mapSetName
in CclScreen class 80
in Public methods 80
MapSetName
in Methods
in Screen COM Class 29
MaxBufferSize (parameter)
in CclBuf class 50
maxRequests
in CclTerminal constructor 87
maxServers
in serverDesc 64
in serverName 65
methodName
in CclException class 67
in Public methods 67
Methods
AbendCode 23
AlterSecurity 4, 36
AppendString 2
AppendText 17
BackgroundColor 18
BackOut 45
BaseAttribute 18
CallType 23
CallTypeText 23
Cancel 5
CCSId 36
Changed 5

Methods (continued)
ChangePassword 5, 36
Column 18
Commit 46
Connect 36
CursorCol 28
CursorRow 28
Data 2
DataTag 18
Depth 28
Details 6
Devtype 37
Diagnose 13, 23, 34, 37
Disconnect 37
DisconnectWithPurge 37
DiscReason 38
ErrorFormat 11, 14
ErrorOffset 11, 14
ErrorWindow 11, 14
ExCode 11, 14, 26, 38
ExCodeText 12, 15, 38
ExtractString 2
FieldByIndex 29
FieldByName 27
FieldByPosition 29
FieldCount 29
Flowid 24
ForceReset 24, 46
ForegroundColor 19
Highlight 19
in Buffer COM Class 2
in Connect COM Class 4
in ECI COM Class 11
in EPI COM Class 13
in Field COM Class 17
in Flow COM Class 23
in Map COM Class 26
in Screen COM Class 28
in Session COM Class 34
in Terminal COM Class 36
in UOW COM Class 45
InputProt 19
InputType 20
InsertString 2
Install 39
Intensity 20
Length 3, 20
Link 7
MakeSecurityDefault 7, 39
MapName 29
MapSetName 29
NetName 39
Overlay 3
Password 7, 39
Poll 24, 39
Methods (continued)
PollForReply 40
Position 20
QueryATI 40
ReadTimeout 40
ReceiveATI 40
ResetDataTag 21
Row 21
Screen 41
Send 41
ServerCount 12, 15
ServerDesc 12, 15
ServerName 8, 12, 16, 41
ServerStatus 8
ServerStatusText 8
SetAID 30
SetATI 41
SetBaseAttribute 21
SetCursor 30
SetData 3
SetErrorFormat 13, 16
SetExtAttribute 21
SetLength 3
SetString 3
SetSyncType 24, 34
SetTermDefns 42
SetText 21
SetTimeout 25
SignonCapability 43
Start 43
State 16, 34, 44
Status 8
String 4
SyncType 25
TermId 44
Terminate 17
Text 22
TextLength 22
Timeout 25
TranDetails 9
TransId 35, 44
Transparency 22
UnpaddedPassword 9
UnpaddedServerName 9
UnpaddedUserid 9
UowId 46
Userid 44
UserId 10
Validate 27
VerifyPassword 10, 44
Wait 25
Width 30
Minutes
in SecTime COM Class 33
Index 241

modified
in BaseMDT 72
in dataTag 68
Month
in SecTime COM Class 33
multipleInstance
in CclECI class 61
N
n (parameter)
in position 70
name (parameter)
in FieldByName 27
namedField
in CclMap class 78
in Protected methods 78
NameSpace parameter
CICS_EciListSystems 129
CICS_EpiAddTerminal function 145
CICS_EpiListSystems function 143
netName
in CclTerminal class 90
in Public methods 90
NetName
in Methods
in Terminal COM Class 39
netname (parameter)
in CclTerminal constructor 86, 87
NetName parameter
CICS_EpiAddExTerminal function 149
CICS_EpiAddTerminal function 145
neutral
in Color 72
New
in Buffer COM Class 1
in Connect COM Class 4
in ECI COM Class 11
in EPI COM Class 13
in Field COM Class 23, 26, 34, 35, 45
newPassword (parameter)
in alterSecurity 56, 57
in AlterSecurity 4, 36
in changed 57
in ChangePassword 5
in changePassword method 88
NewPassword parameter
CICS_ChangePassword function 175
newstate (parameter)
in setATI 92
newUserid (parameter)
in alterSecurity 57
in AlterSecurity 4, 36
no
in Bool 49
in operator!= 54
242 CICS Transaction Gateway: Programming Reference
no (continued)
in operator== 54
in poll 75
normal
in BaseInts 71
in intensity 69
normalHlt
in Highlight 72
notDiscon
in EndTerminalReason 95
Nothing
in Poll 24
NotifyFn parameter
CICS_EpiAddExTerminal function 150
CICS_EpiAddTerminal function 146
numeric
in BaseType 72
in inputType 69
nworkName (parameter)
in Connect 36, 37
in SetTermDefns 42
O
off
in Bool 49
offset (parameter)
in cut 51, 52
in dataArea 52
in ExtractString 2
in insert 53
in InsertString 2
in Overlay 3
in replace 54
OldPassword parameter
CICS_ChangePassword function 175
on
in Bool 49
opaqueTran
in Transparency 73
operator!=
in CclBuf class 54
in Public methods 54
operator+=
in CclBuf class 53, 54
in Public methods 53, 54
operator=
in CclBuf class 53
in Public methods 53
operator==
in CclBuf class 54
in Public methods 54
orange
in Color 72
orTran
in Transparency 72

outofService
in EndTerminalReason 95
Overlay
in Methods
in Buffer COM Class 3
P
PA1
in AID 81
PA3
in AID 81
paleCyan
in Color 72
paleGreen
in Color 72
parameter
in CclMap constructor 77
in CclTerminal constructor 86
in send 92
in setCursor 81
in setExtAttribute 70
password 57
in CclConn class 58, 59
in CclTerminal class 90
in Public methods 58, 59, 90
in verifyPassword method 60
Password
in Methods
in Connect COM Class 7
in Terminal COM Class 39
password (parameter)
in alterSecurity method 88
in CclConn constructor 56
in CclTerminal constructor 87
in ChangePassword 36
in Details 6
in SetTermDefns 42
Password parameter
CICS_EpiSetSecurity function 156
CICS_SetDefaultSecurity function 178
CICS_VerifyPassword function 172
PF1
in AID 81
PF24
in AID 81
pink
in Color 72
poll
in CclFlow class 75
in CclTerminal class 90
in Public methods 75, 90
Poll
in Methods
in Flow COM Class 24
in Terminal COM Class 39
Poll (continued)
in SetSyncType 25, 34
PollForReply
in Methods
in Terminal COM Class 40
position
in CclField class 70
in Public methods 70
Position
in Methods
in Field COM Class 20
programming
reference 47
programName (parameter)
in link 57, 58
in Link 7
protect
in BaseProt 72
in inputProt 69
Protected methods
in CclMap class 78
namedField 78
validate 78
Public methods
abendCode 66, 74
alterSecurity 56, 88
appendText 67, 68
assign 51
backgroundColor 68
backout 95
baseAttribute 68
callType 74
callTypeText 74
cancel 57
CCSid 88
change password 57
changed 57
changePassword 88
className 66
column 68
commit 96
connection 74
cursorCol 79
cursorRow 79
cut 51
dataArea 52
dataAreaLength 52
dataAreaOwner 52
dataAreaType 52
dataLength 52
dataTag 68
depth 80
diagnose 63, 66, 74, 84, 88
disconnect 88, 89
discReason 89
Index 243

Public methods (continued)
exCode 61, 63, 67, 77, 89
exCodeText 61, 64, 67, 78, 89
exObject 67
field 78, 80
fieldCount 80
flowId 74
forceReset 74, 96
foregroundColor 69
handleException 62, 64
handleReply 75, 84
highlight 69
in CclBuf class 51
in CclConn class 56
in CclECI class 61
in CclEPI class 63
in CclException class 66
in CclField class 67
in CclFlow class 74
in CclMap class 77
in CclScreen class 79
in CclSession class 84
in CclTerminal class 88
in CclUOW class 95
inputProt 69
inputType 69
insert 53
install 90
instance 62
intensity 69
length 69
link 57
listState 53, 58, 62, 75, 96
makeSecurityDefault 58, 90
mapName 80
mapSetName 80
methodName 67
netName 90
operator!= 54
operator+= 53, 54
operator= 53
operator== 54
password 58, 59, 90
poll 75, 90
position 70
queryATI 91
readTimeout 91
receiveATI 91
replace 54
resetDataTag 70
row 70
screen 92
send 92
serverCount 62, 64
serverDesc 62, 64
244 CICS Transaction Gateway: Programming Reference
Public methods (continued)
serverName 59, 63, 65, 93
serverStatus 59
serverStatusText 60
setAID 81
setATI 92
setBaseAttribute 70
setCursor 81
setDataLength 55
setExtAttribute 70
setText 71
setTimeout 76
signonCapability 93
state 65, 85, 93
status 59
syncType 76
termID 93
terminal 85
terminate 65
text 71
textLength 71
timeout 76
transID 85, 93
transparency 71
uow 76
uowId 96
userId 60, 93
verifyPassword 60, 94
wait 76
width 81
Public Methods
in SecAttr COM class 31
in SecTime COM Class 32
publications, CICS Transaction Gateway 205
purple
in Color 72
Q
queryATI
in CclTerminal class 91
in Public methods 91
QueryATI
in Methods
in Terminal COM Class 40
R
readTimeout
in CclTerminal class 91
in Public methods 91
ReadTimeout
in Methods
in Terminal COM Class 40
readTimeOut (parameter)
in CclTerminal constructor 87

ReadTimeout (parameter)
in SetTermDefns 42
receiveATI
in CclTerminal class 91
in Public methods 91
ReceiveATI
in Methods
in Terminal COM Class 40
red
in Color 72
replace
in CclBuf class 54
in Public methods 54
reserved1
field in ECI parameter block 98
with ECI_ASYNC call type 109
with ECI_STATE_ASYNC call type 118
with ECI_STATE_SYNC call type 114
with ECI_SYNC call type 102
resetDataTag
in CclField class 70
in Public methods 70
ResetDataTag
in Methods
in Field COM Class 21
in ResetDataTag 21
reverseHlt
in Highlight 72
row
in CclField class 70
in Public methods 70
in validate 79
Row
in Methods
in Field COM Class 21
row (parameter)
in field 78, 80
in setCursor 81
rowPos (parameter)
in FieldByPosition 29
in SetCursor 30
runTran (parameter)
in CclConn constructor 56
in TranDetails 9
S
screen
in CclTerminal class 92
in Public methods 92
Screen
in Field COM Class 17
in Methods
in Terminal COM Class 41
in Screen 41
in Screen COM class 28
Screen (continued)
in Validate 27
screen (parameter)
in CclMap constructor 77
in handleReply 84
Screen COM class
Methods
CursorCol 28
CursorRow 28
Depth 28
FieldByIndex 29
FieldByPosition 29
FieldCount 29
MapName 29
MapSetName 29
SetAID 30
SetCursor 30
Width 30
Screen.fieldbyIndex method
in Ccl Field COM class 17
screenRef (parameter)
in Validate 27
Seconds
in SecTime COM Class 33
send
in CclTerminal class 92
in Public methods 92
Send
in Methods
in Terminal COM Class 41
in Poll 39
in SetSyncType 34
SenseCode parameter
CICS_EpiSenseCode function 162
server
in poll 91
in State 85, 94
server (parameter)
in CclTerminal constructor 86, 87
serverCount
in CclECI class 62
in CclEPI class 64
in Public methods 62, 64
ServerCount
in Methods
in ECI COM Class 12
in EPI COM Class 15
serverDesc
in CclECI class 62
in CclEPI class 64
in Public methods 62, 64
ServerDesc
in ExCode 15
in Methods
in ECI COM Class 12
Index 245

ServerDesc (continued)
in Methods (continued)
in EPI COM Class 15
serverName
in CclConn class 59
in CclECI class 63
in CclEPI class 65
in CclTerminal class 93
in Public methods 59, 63, 65, 93
ServerName
in Details 6
in ExCode 15
in Methods
in Connect COM Class 8
in ECI COM Class 12
in EPI COM Class 16
in Terminal COM Class 41
serverName (parameter)
in CclConn constructor 56
in Details 6
serverStatus
in CclConn class 59
in Public methods 59
ServerStatus
in CclConn class 60
in Enumerations 60
in Methods
in Connect COM Class 8
serverStatusText
in CclConn class 60
in Public methods 60
ServerStatusText
in Methods
in Connect COM Class 8
servName (parameter)
in Connect 36, 37
in SetTermDefns 42
Session
in Send 41
in Session COM Class 33
in SetSyncType 34
in Start 43
in State 44
session (parameter)
in ReceiveATI 41
in receiveATI method 91
in send 92
in Send 41
in Start 43
Session COM class
Methods
Diagnose 34
SetSyncType 34
State 34
TransId 35
246 CICS Transaction Gateway: Programming Reference
setAID
in CclScreen class 81
in Public methods 81
SetAID
in Methods
in Screen COM Class 30
setATI
in CclTerminal class 92
in Public methods 92
SetATI
in Methods
in Terminal COM Class 41
setBaseAttribute
in CclField class 70
in Public methods 70
SetBaseAttribute
in Methods
in Field COM Class 21
setCursor
in CclScreen class 81
in Public methods 81
SetCursor
in Methods
in Screen COM Class 30
SetData
in Methods
in Buffer COM Class 3
setDataLength
in CclBuf class 55
in Public methods 55
SetErrorFormat
in Methods
in ECI COM Class 13
in EPI COM Class 16
setExtAttribute
in CclField class 70
in Public methods 70
SetExtAttribute
in Methods
in Field COM Class 21
SetLength
in Buffer COM Class 1
in Methods
in Buffer COM Class 3
SetString
in Methods
in Buffer COM Class 3
SetSyncType
in Methods
in Flow COM Class 24
in Session COM Class 34
SetTermDefns
in Methods
in Terminal COM Class 42

setText
in CclField class 71
in Public methods 71
SetText
in Methods
in Field COM Class 21
setTimeout
in CclFlow class 76
in Public methods 76
SetTimeout
in Methods
in Flow COM Class 25
shutdown
in EndTerminalReason 95
signoff
in EndTerminalReason 95
signonCapability
in CclTerminal class 93
in Public methods 93
SignonCapability
in Methods
in Terminal COM Class 43
signonCapability (parameter)
in CclTerminal constructor 87
in SetTermDefns 42
signonCapable
in signonType 94
signonIncapable
in signonType 94
signonType
in CclTerminal class 94
in Enumerations 94
signonUnknown
in signonType 94
Size parameter
CICS_EpiReply function 160
CICS_EpiStartTran function 158
stackPages (parameter)
in CclFlow 73
Start
in Methods
in Terminal COM Class 43
in Poll 39
in SetSyncType 34
startdata (parameter)
in send 92
startData (parameter)
in Start 43
state
in CclEPI class 65
in CclSession class 85
in CclTerminal class 93
in Public methods 65, 85, 93
State
in CclEPI class 65
State (continued)
in CclSession class 85
in CclTerminal class 94
in Enumerations 65, 85, 94
in EPI COM Class 13
in Methods
in EPI COM Class 16
in Session COM Class 34
in Terminal COM Class 44
in State 44
state (parameter)
in handleReply 84
stateVal (parameter)
in SetATI 41, 42
status
in CallType 77
in CclConn class 59
in Public methods 59
in ServerStatus 8
in ServerStatusText 8
in SetSyncType 25
Status
in Details 6
in Methods
in Connect COM Class 8
in Poll 24
String
in Methods
in Buffer COM Class 4
string (parameter)
in AppendString 2
in InsertString 2
in Overlay 3
in SetString 3, 4
sync
in CclSession constructor 84
in Sync 49
Sync
in Ccl class 49
in Enumerations 49
syncType
in CclFlow class 76
in poll 75, 91
in Public methods 76
in wait 76
SyncType
in Methods
in Flow COM Class 25
syncType (parameter)
in CclFlow 73
in CclSession constructor 84
in SetSyncType 24, 34
in SyncType 25
SysErr parameter
CICS_EpiGetSysError function 165
Index 247

system information structure 129, 143
System parameter
CICS_ChangePassword function 175
CICS_EpiAddExTerminal function 148
CICS_EpiAddTerminal function 145
CICS_SetDefaultSecurity function 178
CICS_VerifyPassword function 172
SystemName parameter
CICS_EciListSystems 129
Systems parameter 130
CICS_EciListSystems 129
CICS_EpiListSystems function 143
T
termDefined
in State 94
termID
in CclTerminal class 93
in Public methods 93
TermId
in Methods
in Terminal COM Class 44
terminal
in CclSession class 85
in Public methods 85
Terminal
in EPI COM Class 13
in Screen COM Class 28
in ServerName 41
Terminal COM class
Methods
AlterSecurity 36
CCSId 36
ChangePassword 36
Connect 36
Devtype 37
Diagnose 37
Disconnect 37
DisconnectWithPurge 37
DiscReason 38
ExCode 38
ExCodeText 38
Install 39
MakeSecurityDefault 39
NetName 39
Password 39
Poll 39
PollForReply 40
QueryATI 40
ReadTimeout 40
ReceiveATI 40
Screen 41
Send 41
ServerName 41
SetATI 41
248 CICS Transaction Gateway: Programming Reference
Terminal COM class (continued)
Methods (continued)
SetTermDefns 42
SignonCapability 43
Start 43
State 44
TermId 44
TransId 44
Userid 44
VerifyPassword 44
terminal index 144, 148
Terminal.Connect
in Screen COM Class 28
Terminal.Screen
in Screen COM Class 28
terminate
in CclEPI class 65
in Public methods 65
Terminate
in Methods
in EPI COM Class 17
in Terminate 17
TermIndex parameter
CICS_EpiAddExTerminal function 150
CICS_EpiAddTerminal function 146
CICS_EpiATIState function 161
CICS_EpiDelTerminal function 154
CICS_EpiGetEvent function 163
CICS_EpiGetSysError function 165
CICS_EpiInquireSystem function 153
CICS_EpiPurgeTerminal function 155
CICS_EpiReply function 160
CICS_EpiSenseCode function 162
CICS_EpiSetSecurity function 156
CICS_EpiStartTran function 157
text
in CclField class 71
in Public methods 71
Text
in Methods
in Field COM Class 22
text (parameter)
in appendText 68
in CclBuf 51
in operator+= 54
in operator= 53
in setText 71
textLength
in CclField class 71
in Public methods 71
TextLength
in Methods
in Field COM Class 22
textString (parameter)
in AppendText 17, 18

textString (parameter) (continued)
in SetText 21, 22
timeout
in CclFlow class 76
in Public methods 76
Timeout
in Methods
in Flow COM Class 25
timeout (parameter)
in CclFlow 73
in Install 39
in setTimeout 76
tranCode (parameter)
in Start 43
TranDetails
in Connect COM Class 4
in Methods
in Connect COM Class 9
transID
in CclSession class 85
in CclTerminal class 93
in Public methods 85, 93
TransId
in Methods
in Session COM Class 35
in Terminal COM Class 44
transid (parameter)
in send 92
TransId parameter
CICS_EpiStartTran function 157
transparency
in CclField class 71
in Public methods 71
Transparency
in CclField class 72
in Enumerations 72
in Methods
in Field COM Class 22
true
in ErrorWindow 11, 14
True
in Poll 24, 39
TRUE
in Validate 27
txnTimedOut
in State 94
type (parameter)
in CclBuf 50, 51
U
unavailable
in ServerStatus 61
underscoreHlt
in Highlight 72
unit (parameter)
in link 57, 58
unitOfWork (parameter)
in Link 7
unknown
in EndTerminalReason 95
in ServerStatus 60
unknownServer
in CclTerminal constructor 86
unmodified
in BaseMDT 72
in dataTag 68
unmodified (parameter)
in resetDataTag 70
unpadded (parameter)
in status 59, 60
UnpaddedPassword
in Methods
in Connect COM Class 9
UnpaddedServerName
in Methods
in Connect COM Class 9
UnpaddedUserid
in Methods
in Connect COM Class 9
unprotect
in BaseProt 72
in inputProt 69
uow
in CclFlow class 76
in Public methods 76
UOW
in Link 7
in UOW COM class 45
UOW COM class
Methods
BackOut 45
Commit 46
ForceReset 46
UowId 46
uowId
in CclUOW class 96
in Public methods 96
UowId
in Methods
in UOW COM Class 46
userId
in CclConn class 60
in CclTerminal class 93
in Public methods 60, 93
Userid
in Methods
in Terminal COM Class 44
Index 249

UserId
in Methods
in Connect COM Class 10
userid (parameter)
in alterSecurity method 88
in CclTerminal constructor 87
in SetTermDefns 42
userId (parameter)
in CclConn constructor 56
in Details 6
userID (parameter)
in CclConn constructor 56
in Details 6
UserId parameter
CICS_ChangePassword function 174
CICS_EpiSetSecurity function 156
CICS_SetDefaultSecurity function 178
CICS_VerifyPassword function 172
V
validate
in CclMap class 78
in Protected methods 78
Validate
in Methods
in Map COM Class 27
value (parameter)
in setExtAttribute 70
Value (parameter)
in SetExtAttribute 21
verifyPassword
in CclConn class 60
in CclTerminal class 94
in Public methods 60, 94
VerifyPassword
in Methods
in Connect COM Class 10
in Terminal COM Class 44
Version parameter
CICS_EpiInitialize function 141
W
wait
in CclFlow class 76
in Public methods 76
Wait
in Methods
in Flow COM Class 25
in Wait 25
Wait parameter
CICS_EpiGetEvent function 164
white
in Color 72
width
in CclScreen class 81
250 CICS Transaction Gateway: Programming Reference
width (continued)
in Public methods 81
in validate 79
Width
in Methods
in Screen COM Class 30
withPurge
in disconnect method
in CclTerminal class 89
X
xorTran
in Transparency 72
Y
Year
in SecTime COM Class 33
yellow
in Color 72
yes
in Bool 49
in operator!= 54
in operator== 54
in poll 75

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.
© Copyright IBM Corp. 1989, 2002 251

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 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.
COPYRIGHT LICENSE:
This information contains sample application programs in source language,
which illustrate programming techniques on various operating platforms. You
may copy, modify, and distribute these sample programs in any form without
payment to IBM for the purposes of developing, using, marketing, or
distributing application programs conforming to IBM’s application
programming interfaces for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability,
serviceability, or function of these programs.
252 CICS Transaction Gateway: Programming Reference

Trademarks
The following terms are trademarks of International Business Machines
Corporation in the United States, or other countries, or both:
AIX CICS
IBM OS/390
VisualAge
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 of Sun
Microsystems, Inc. in the United States, or other countries, or both.
Other company, product or service names may be trademarks or service
marks of others.
Notices 253

254 CICS Transaction Gateway: Programming Reference

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. 1989, 2002 255

����
Program Number: 5724-D12
Printed in U.S.A.
SC34-6140-00

Spine information:
��� CICS Transaction Gateway Programming Reference Version 5.0

CICS Transaction Gateway
Messages
Version 5.0
���
SC34-6193-00

CICS Transaction Gateway
Messages
Version 5.0
���
SC34-6193-00

Note!
Before using this information and the product it supports, be sure to read the general information under
“Notices” on page 143.
First Edition (July 2002)
This edition applies to Version 5.0 of IBM CICS ® Transaction Gateway program number 5724-D12.
© Copyright International Business Machines Corporation 1994, 2002. 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. . . . . . . . . . . v
Conventions and terminology used in this
book . . . . . . . . . . . . . . . v
Prerequisite and related information . . . . v
How to send your comments . . . . . . v
Obtaining books from IBM . . . . . . . vi
Messages . . . . . . . . . . . . . 1
The product library and related literature 123
CICS Transaction Gateway books . . . . 123
Sample configuration documents. . . . . 124
Redbooks . . . . . . . . . . . . 125
Other Useful Books . . . . . . . . . 125
CICS Transaction Server publications . . 125
APPC-related publications . . . . . . 126
|
|
TCP62–related publications . . . . . 126
Obtaining books from IBM. . . . . . . 126
Accessibility . . . . . . . . . . . 127
Documentation . . . . . . . . . . 127
Glossary . . . . . . . . . . . . 129
Index . . . . . . . . . . . . . 141
Notices . . . . . . . . . . . . . 143
Trademarks . . . . . . . . . . . . 144
Sending your comments to IBM . . . . 145
© Copyright IBM Corp. 1994, 2002 iii

iv CICS Transaction Gateway: CICS Transaction Gateway Messages

About this book
This book lists the error messages for the CICS Transaction Gateway Version
5.0 and the CICS Universal Client products. Significant information messages
are also listed.
It is intended for use as a quick reference, with messages organized in
alphanumeric sequence. Each message entry gives the message identifier,
message text, and further diagnostic and explanatory information.
Conventions and terminology used in this book
The terminology in this book should be familiar to anyone who has used
CICS and the supported operating systems.
Prerequisite and related information
The messages refer to several non-IBM books; these mainly relate to the
platform on which the client is running and it is assumed that these books are
available to you.
How to send your comments
Your feedback is important in helping to provide the most accurate and
high-quality information. If you have any comments about this book, or any
other CICS documentation:
v Visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link to our feedback form.
Here you will find the feedback page where you can enter and submit your
comments.
v Send your comments by e-mail to idrcf@hursley.ibm.com
v Fax your comments to:
+44 1962 842327 (if you are outside the UK)
01962 842327 (if you are in the UK)
v Mail your comments to:
Information Development
Mail Point 095
© Copyright IBM Corp. 1994, 2002 v

IBM United Kingdom Laboratories
Hursley Park
Winchester
Hampshire
SO21 2JN
United Kingdom
Whichever method you use, ensure that you include:
v The name of the book
v The form number of the book
v If applicable, the version of the product
v The specific location of the text you are commenting on, for example, a
page number or table number.
When you send information to IBM, you grant IBM a non-exclusive right to
use or distribute the information in any way it believes appropriate without
incurring any obligation to you.
Obtaining books from IBM
For information on books you can download, visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link.
You can order hardcopy books:
v Through your IBM representative or the IBM branch office serving your
locality.
v By calling 1-800-879-2755 in the United States.
v From the Web site at:
www.ibm.com/shop/publications/order
vi CICS Transaction Gateway: CICS Transaction Gateway Messages

Messages
CCL0510E Command option option is invalid
Explanation: An invalid command option was
specified on the command line.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0511E Command option option must
specify a value
Explanation: A command line application was
run with no value supplied for the named
required option.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0512E Command option option cannot be
used more than once
Explanation: The named option was used more
than once on the command line. This is invalid.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0513E Command option option1 cannot
be used with option option2
Explanation: The two named options, used on
the command line, were incompatible.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0514E Command option option1 or
option2 must be provided
Explanation: The command line did not include
one of the named required options.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0515E Command option option1 can only
be used with option2
Explanation: option1 was specified on the
command line, but option2 was not also specified.
This is invalid.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0516E Command option option is invalid
Explanation: An invalid command option was
specified on the command line.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0517E Command option option must
specify a value
Explanation: A command line application was
run with no value supplied for the named
required option.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
© Copyright IBM Corp. 1994, 2002 1

CCL0518E CCL1024E
CCL0518E Command option option cannot be
used more than once
Explanation: The named option was used more
than once on the command line. This is invalid.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0519E Command option option1 cannot
be used with option option2
Explanation: The two named options, used on
the command line, were incompatible.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0520E Command option option1 or
option2 must be provided
Explanation: The command line did not include
one of the named required options.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL0521E Command option option1 can only
be used with option2
Explanation: option1 was specified on the
command line, but option2 was not also specified.
This is invalid.
System Action: The command line application
terminates.
User Response: Retype the command using the
correct options.
CCL1021E Unable to write to text file filename
Explanation: The binary trace formatter is
unable to write any further information to the
2 CICS Transaction Gateway: CICS Transaction Gateway Messages
CICS client trace file during conversion of the
binary trace.
System Action: The binary trace formatter
terminates.
User Response: Determine the cause of the
error. It may be that the disk which the binary
trace formatter is writing to is full, or the disk
might be write-protected.
CCL1022E Unable to read from binary file
filename
Explanation: The binary trace formatter is
unable to read from the binary trace file during
conversion of the binary trace.
System Action: The binary trace formatter
terminates.
User Response: Determine the cause of the
error. It may be that the binary trace file has
been removed during conversion, or the binary
trace file might be read-protected.
CCL1023E Unable to open file filename
Explanation: The binary trace formatter is
unable to open the specified file for reading or
writing as required.
System Action: The binary trace formatter
terminates.
User Response: Determine the cause of the
error. If the file that is being opened is the binary
trace file, check that the file exists and that it is
not read-protected. If the file that is being
opened is the output text file, make sure that the
disk on to which the file is being written is not
write-protected.
CCL1024E Unable to correctly interpret all
bytes of file filename
Explanation: The binary trace formatter is
unable to process the specified binary trace file.
System Action: The binary trace formatter
terminates.
User Response: Determine the cause of the
error. Make sure that the file being read is a

valid binary trace file, and that it was created
with the version of the CICS client currently
installed on your system. If after checking this
you still receive the same error, you may need to
remove the binary trace file before running the
client trace again.
CCL1025E Not enough memory to convert
binary trace file
Explanation: The binary trace formatter has run
out of free memory whilst processing the binary
trace.
System Action: The binary trace formatter
terminates.
User Response: Increase the amount of
available memory in the system by shutting
down applications that are not needed, and then
re-run the binary trace formatter. You can reduce
the amount of memory that the binary trace
formatter needs by specifying on the command
line the maximum amount of data to convert at
any one time (refer to the documentation for
further information on how to do this).
CCL1027E Invalid binary trace file filename
(version number = number)
Explanation: The binary trace formatter
detected an invalid version number in the binary
trace file.
System Action: The binary trace formatter
terminates without performing any further
processing.
User Response: Make sure that the file you are
trying to convert is a valid binary trace file and
that you are using the most recent version of the
binary trace formatter that is available on your
system.
CCL1028E Unable to access the file filename
Explanation: The binary trace formatter is
unable to access the binary trace file.
System Action: The binary trace formatter
terminates.
CCL1025E CCL1032I
User Response: Check that the user has access
to the binary trace file.
CCL1030I Warning: component component
was not found in the binary trace
Explanation: The binary trace formatter was
told to process trace points from a named
component, but no trace points from that
component were found in the binary trace file.
System Action: This message is for information
only. The binary trace formatter will continue to
process the binary trace file.
User Response: In order to stop this message
being displayed, make sure that all the
components you specify on the command line of
the binary trace formatter exist in the binary
trace.
CCL1031I [Bytes Remaining - bytes
(percentage)]
Explanation: The binary trace formatter has
been started and is in the process of converting
the binary trace. The message shows the progress
that the binary trace formatter has made so far.
System Action: This message is for information
only. The binary trace formatter will continue to
process the binary trace file.
User Response: No further action is required
CCL1032I Do you want to overwrite filename
[Y|N]?
Explanation: The binary trace formatter has
detected that the trace file you have told it to
generate already exists. You are given the
opportunity to erase it or terminate the formatter.
System Action: If you enter Y at the command
prompt, the binary trace formatter will continue
and the old trace file will be overwritten. If you
enter N at the command prompt, the binary trace
formatter will terminate and the old trace file
will remain unchanged.
User Response: Select the appropriate option
according to whether you want to overwrite the
Messages 3

CCL1046 CCL1124I
old trace file or terminate the binary trace
formatter.
CCL1046 Error in function function (Error
code = error)
Explanation: An system or internal client
function failed.
System Action: The message is written to the
error log. The function name and error code are
logged.
User Response: If the problem persists, contact
your service organization.
CCL1047 Error in the EPI (function, error,
termid)
Explanation: An internal EPI error has occurred.
System Action: The message is written to the
error log. The function name and error code are
logged, together with the TermId.
User Response: If the problem persists, contact
your service organization.
CCL1100I The following list shows what
components can be traced
Explanation: A request to list all client
components has been given.
System Action: A list of all client components is
displayed on the screen. An X is placed beside
each component that is currently being traced.
User Response: No further action is required
CCL1120I Trace has not been started
Explanation: A command that required tracing
to be turned on was given, but at the moment
tracing is disabled.
System Action: Some client commands that
require tracing to be turned on will fail, but most
requests to the client will be unaffected.
User Response: If you want to issue requests to
the client that rely on tracing, tracing must be
turned on.
4 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL1121I Component trace started to:
component list
Explanation: A request to trace only those
components specified on the command line was
given.
System Action: The client runs as normal,
writing all trace points from the specified
components to the binary trace file.
User Response: No further action is required.
CCL1122E Invalid list of components. Please
re-type.
Explanation: You have specified a list of
components on the command line, but one or
more of the components in the list is invalid.
System Action: The request that required a list
of components to be specified is ignored.
User Response: Refer to the CICS client
documentation for a list of valid components and
retype the request.
CCL1123I Reading binary trace file filename
Explanation: The binary trace formatter is about
to process the specified binary trace file.
System Action: This message is for information
only. The binary trace formatter will continue.
User Response: No further action is required
CCL1124I Reading binary trace file filename1
and filename2
Explanation: The binary trace formatter is about
to process the specified binary trace files. The
binary trace formatter is reading from two trace
files because it is formatting a wrapping trace.
Refer to the documentation for further
information about wrapping traces.
System Action: This message is for information
only. The binary trace formatter will continue.
User Response: No further action is required

CCL1125I Generating text trace file filename
Explanation: The binary trace formatter will
write all text formatted output to the specified
file.
System Action: This message is for information
only. The binary trace formatter will continue.
User Response: No further action is required
CCL1126I Failed to make new trace
component list persistent
Explanation: When the list of trace components
is changed, the new list is stored as the default.
If there is a problem storing this new list then
this message will be produced. Your current trace
session will still use the components you
specified but they will not become the default so
if you turn trace off and on again, you will need
to re-specify the component list.
System Action: This message is for information
only. The client will continue.
User Response: No further action is required
CCL1127I Updated trace component list to:
list
Explanation: The client has updated the list of
components to trace and this list will be the
default until the client is restarted (when the
default will be refreshed from the initialisation
file). For instance, if you stop and restart tracing,
the components to trace will remain the same
unless you make another change explicitly.
System Action: This message is for information
only. The client will continue.
User Response: No further action is required
CCL1128I Generating text summary trace
file filename
Explanation: The binary trace formatter will
write all summary text formatted output to the
specified file.
System Action: This message is for information
only. The binary trace formatter will continue.
CCL1125I CCL1202
User Response: No further action is required
CCL1200 Unable to open binary trace file
filename
Explanation: The client cannot open the binary
trace file for writing.
System Action: The client will continue, but
tracing will be disabled.
User Response: Check that the directory into
which the binary trace file is being written is not
write-protected.
CCL1200E TCP62 Trace Formatter: Network
Protocol Format Syntax Error.
Explanation: A syntax error was found while
processing the NPF template files used to format
TCP62 data flows.
System Action: The trace formatter will not
format any more TCP62 data flows, but will
continue to format other parts of the trace.
User Response: Contact your service
organisation.
CCL1201E TCP62 Trace Formatter: Network
Protocol Format Run-time Error.
Explanation: A run-time error was found while
processing the NPF template files used to format
TCP62 data flows.
System Action: The trace formatter will stop
formatting the current TCP62 data flow, but it
will continue to format other TCP62 data flows
and other parts of the trace.
User Response: Contact your service
organisation.
CCL1202 Unable to write to binary trace
file
Explanation: Although the binary trace file was
opened successfully, an error occurred whilst
writing a trace point to the file.
System Action: The client will continue, but
tracing will be disabled.
Messages 5

CCL1202E CCL1207
User Response: Check that the permissions of
the trace file have not changed.
CCL1202E The remaining TCP62 data flows
will not be formatted.
Explanation: A severe error was found while
processing the NPF template files used to format
TCP62 data flows.
System Action: The trace formatter will not
format any more TCP62 data flows, but will
continue to format other parts of the trace.
User Response: Contact your service
organisation.
CCL1203 Out of memory whilst running
with trace on
Explanation: There is not enough available
memory for tracing to continue.
System Action: The client will continue, but
tracing will be disabled.
User Response: Make more memory available
to the client and then try again.
CCL1203E The remaining part of this TCP62
data flow will not be formatted.
Explanation: An error was found while
processing the NPF template files used to format
TCP62 data flows.
System Action: The trace formatter will stop
formatting the current TCP62 data flow, but it
will continue to format other TCP62 data flows
and other parts of the trace.
User Response: Contact your service
organisation.
CCL1204 No memory buffer - unable to
perform tracing operations
Explanation: This is a serious internal error, and
means that the client is unable to buffer its
writes to the trace file.
System Action: The client will continue, but
tracing will be disabled.
6 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: If the problem persists, contact
your service organisation.
CCL1204E Network Protocol Formatter Error:
error description.
Explanation: The error described here was
found while processing the NPF template files
used to format TCP62 data flows.
System Action: The following CCL1202E or
CCL1203E error message describes what will
happen.
User Response: Contact your service
organisation.
CCL1205 Invalid system return code
(Function, Error code)
Explanation: An internal system function has
returned an error whilst tracing was turned on.
System Action: The client will continue, but
tracing will be disabled.
User Response: If the problem persists, contact
your service organisation.
CCL1206 Internal error (Function, Error)
Explanation: An internal function has returned
an error whilst tracing was turned on.
System Action: The client will continue, but
tracing will be disabled.
User Response: If the problem persists, contact
your service organisation.
CCL1207 Security failure - the owner of the
binary trace file has changed
Explanation: This message will appear in the
log file on UNIX if the owner of the trace file
changes. For security reasons, you may not
change the owner of the trace file whilst trace is
running.
System Action: The client will continue, but
tracing will be disabled.
User Response: Restart trace and make sure

that the owner of the trace file does not change.
CCL1208 Trace initialization failure.
Explanation: An internal error prevented
tracing from being turned on.
System Action: The Client daemon will
continue, but tracing is disabled.
User Response: If the problem persists, contact
your service organisation.
CCL1209 Trace file deleted whilst tracing
active.
Explanation: The trace file was deleted whilst
tracing was active.
System Action: This message is written to the
error log. Tracing will continue.
User Response: Deleting the trace file whilst
tracing is active is not recommended. To limit the
size of the trace file, set the maximum client
wrap size. See the administration guide for more
details.
CCL1210 Trace component component is
invalid and will be ignored
Explanation: You are trying to trace to a
component that is not valid.
System Action: Tracing will continue, but the
component you have specified will be ignored.
User Response: If you don’t want this message
to appear in the log, remove the reference to the
invalid component.
CCL2001E Server server is undefined
Explanation: The client received a request for a
server, but the server is not defined in the client
initialization file that was specified when the
client first started up.
System Action: The request fails but the client
continues.
User Response: Ensure the server name
specified by the ECI or EPI application, or by the
CCL1208 CCL2006I
3270 Emulator is correct. If required, add the
server name to the client initialization file, then
stop and restart the client to activate the changes.
CCL2003I Server server requires a security
identification
Explanation: The client received a request
destined for a secure server. The server required
a valid userid and password before it could
accept the request, and was supplied either with
an invalid one or none at all.
System Action: The client displays a pop-up
panel allowing a userid and password to be
entered or the request to be cancelled.
User Response: Enter a valid userid and
password to allow the request to be processed by
the server. This message can be avoided either by
ensuring that an ECI application supplies a valid
userid and password or by using the CICSCLI
/C command to set the server security.
CCL2004E The client cannot continue
Explanation: An error was detected.
System Action: The client terminates.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL2005I The client will continue
Explanation: An error was detected.
System Action: Client processing continues.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL2006I Refer to the client error log for
more details
Explanation: An error has occurred for which
further useful diagnostic information has been
written to the client error log.
System Action: Error information is written to
the client error log.
Messages 7

CCL2007E CCL2014
User Response: Examine the client error log to
obtain the information.
CCL2007E Free memory is exhausted
Explanation: The client ran out of memory
while processing a request.
System Action: The request fails and the client
attempts to continue processing.
User Response: Try altering the values in the
client initialization file to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL2008E An internal state error occurred
Explanation: The client detected an unexpected
internal error.
System Action: Error information is written to
the client error log.
User Response: Obtain the client error log -
and, if possible, trace information - and refer the
problem to your support organization.
CCL2009E An unexpected error has occurred
Explanation: The client detected an unexpected
error.
System Action: Error information is written to
the client error log.
User Response: Obtain the client error log -
and, if possible, trace information - and refer the
problem to your support organization.
CCL2010 Internal transport error (function,
error)
Explanation: An internal client function failed.
System Action: The message is written to the
error log and the client terminates. The function
name and error code are logged.
User Response: If the problem persists, contact
your service organization.
8 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL2011 Out of memory creating session
control structure
Explanation: The client was unable to allocate
enough memory to create an internal control
structure for a new server conversation.
System Action: The message is written to the
error log and processing continues. The
conversation is not created.
User Response: Try altering the values in the
client initialization file to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL2012 Unable to find session entry
(session id, slot number)
Explanation: The client was unable to locate an
internal control structure for an existing server
conversation.
System Action: The message is written to the
error log and processing continues. The
conversation is ended.
User Response: If the problem persists, contact
your service organization.
CCL2013 Out of memory creating terminal
control structure
Explanation: The client was unable to allocate
enough memory to create an internal control
structure associated with an emulator or EPI
terminal.
System Action: The message is written to the
error log and processing continues. The control
structure is not created.
User Response: Try altering the values in the
client initialization file to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL2014 Unable to find terminal entry
(session id, index, name)
Explanation: The client was unable to locate an
internal control structure associated with a
terminal or EPI program. This may occur if an

ATI request is received for a terminal that no
longer exists because either the client or the
terminal was shut while the ATI was in transit.
System Action: The message is written to the
error log and client processing continues but the
emulator may be unable to continue.
User Response: If the problem persists, contact
your service organization.
CCL2015 Unable to find server entry (link
id)
Explanation: The client received an event
associated with an unconnected server.
System Action: The message is written to the
error log and processing continues. The event is
ignored.
User Response: If the problem persists, contact
your service organization.
CCL2016 Invalid communications event
identifier (event id)
Explanation: The client received an unknown
event from one of the communications protocol
drivers.
System Action: The message is written to the
error log and processing continues. The event is
ignored.
User Response: If the problem persists, contact
your service organization.
CCL2018 Internal function error (function,
error)
Explanation: An internal function failed.
System Action: The message is written to the
error log and processing continues. The function
name and error code are logged.
User Response: If the problem persists, contact
your service organization.
CCL2021 ECI request (SessId=session,
Slot=slot, Type=type)
Explanation: The client received an ECI request.
The session value identifies the application and
the slot value identifies the unit of work. The
message is followed by the application’s ECI
parameter block.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2022 ECI COMMAREA Data:
Length=length Null Stripped
Length=null stripped length
Explanation: The client received an ECI request.
The length value gives the length of the
application’s COMMAREA. The null stripped
length gives the length of the COMMAREA after
some, or all, of the trailing nulls have been
removed. The message is followed by the
COMMAREA data.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2023 Client Response (SessId=session,
Slot=slot, ReqRC=value1,
AppRC=value2)
Explanation: The client sent a response to an
application. The session and slot values identify
the application receiving the response. The value1
and value2 values contain the response return
codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2015 CCL2024
CCL2024 Unknown application
(SessId=session)
Explanation: The client tried to send a response
to an unknown application. Often this occurs if
the application has ended before its response was
Messages 9

CCL2025 CCL2031
received. The session value identifies the
application.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2025 ECI request held (SessId=session,
Slot=slot)
Explanation: The client held an ECI request
while the connection to a server was established.
The session and slot values identify the
application.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2026 Server List request (SessId=session,
Space=size)
Explanation: The client received a request to
supply a list of server names and descriptions.
The session value identifies the application
issuing the request and the size value indicates
the amount of space provided to contain the
result.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2027 Server Status request
(SessId=session, Space=size)
Explanation: The client received a request to
supply a list of active server names, descriptions,
and status. The session value identifies the
application issuing the request and the size value
indicates the amount of space provided to
contain the result.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
10 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL2028 Server Start request
(SessId=session)
Explanation: The client received a request to
start a connection to a server. The session value
identifies the application issuing the request. The
message is followed by the name of the required
server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2029 Server Stop request
(SessId=session, Type=type)
Explanation: The client received a request to
stop a connection to a server. The session value
identifies the application issuing the request and
type indicates if a stop or abort was requested.
The message is followed by the name of the
required server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2030 Server Security request
(SessId=session)
Explanation: The client received a request to set
server security logon information. The session
value identifies the application issuing the
request. The message is followed by the new
security details.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2031 Closedown request
(SessId=session, Type=type)
Explanation: The client received a request to
terminate. The session value identifies the
application issuing the request and type indicates
if a stop or abort was requested.
System Action: The message is written to the
trace file if tracing is enabled.

User Response: None.
CCL2032 Application terminated
(SessId=session)
Explanation: The client received a notification
that an application has terminated. The session
value identifies the terminating application.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2034 TR Install request (SessId=session,
TermId=index, Type=type)
Explanation: The client received a request to
install a terminal from an emulator or EPI
application. The session value identifies the
application, the index value gives the EPI
terminal index and the type value identifies an
emulator or EPI request. The message is followed
by the requested terminal install details.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2035 TR request (SessId=session,
TermId=index, Type=type)
Explanation: The client received a terminal
request from an emulator or EPI application. The
session value identifies the application, the index
value gives the EPI terminal index and the type
value identifies an emulator or EPI request.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2036 TR TIOA Data: Length=length
Explanation: The client received a terminal
request from an emulator or EPI application. The
length value gives the length of the terminal or
application’s TIOA data. The message is followed
by the TIOA data.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2037 TR Install request held
(SessId=session, TermId=index)
Explanation: The client held an emulator or EPI
request while the connection to a server was
established. The session and index values identify
the application and terminal.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2038 Service Trace Enable request
(SessId=session)
Explanation: The client received a request to
enable service tracing. The session value identifies
the application issuing the request.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2040 Service Trace Disable request
(SessId=session)
Explanation: The client received a request to
disable service tracing. The session value
identifies the application issuing the request.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2032 CCL2044
CCL2044 Out of memory creating client
control structure
Explanation: The client was unable to allocate
enough memory to create an internal control
structure.
System Action: The message is written to the
error log and processing continues if possible.
User Response: Try altering the values in the
client initialization file to provide the client with
a larger free memory pool or to reduce the
Messages 11

CCL2045 CCL2055
overall memory requirements.
CCL2045 Request directed to server server
Explanation: The client routed a request to the
named server. The server value identifies the
server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2048 Maximum trace data size set to
size
Explanation: The client set the maximum trace
data size. The size value indicates the new
maximum trace data size.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2050 Error and Logon prompt request
(SessId=session, Type=type)
Explanation: The client received a request to
enable or suppress error and logon prompts. The
session value identifies the application issuing the
request and the type value indicates the request
type.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2051 CICS system transaction tran
failed on server server
Explanation: A client system transaction failed
to run on the named server. If connecting to a
CICS/400 server, a failure of transaction CCIN
indicates that the server is not available. The tran
value indicates the name of the failed transaction
and server indicates the failing server.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
12 CICS Transaction Gateway: CICS Transaction Gateway Messages
your service organization.
CCL2052E Cannot open error log file file
name
Explanation: The client could not open or write
to the specified error log file.
System Action: Log messages are lost.
User Response: Check that the name specified
in the LogFile parameter in the client
initialization file is correct and accessible.
CCL2053I Cannot open trace file file name -
tracing has been disabled
Explanation: The client could not open or write
to the specified trace file.
System Action: Trace information is lost.
User Response: Check that the name specified
in the TraceFile parameter in the client
initialization file is correct and accessible.
CCL2054I A CICS server error has occurred
Explanation: An error occurred on a CICS
server with which the client was trying to
communicate.
System Action: Error information is written to
the client error log; client processing continues.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL2055 Connection with server
established (LinkId=link)
Explanation: The client established a connection
with a server. The link value identifies the server
to which the connection was established.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.

CCL2056 Connection with server lost
(LinkId=link)
Explanation: The client lost a connection with a
server. The link value identifies the server to
which the connection was lost.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2057 Incoming conversation request
(LinkId=link, ConvId=conv)
Explanation: The client received an indication
from a server that a new conversation should be
established. The link value identifies the server
requesting the conversation and the conv value
identifies the new conversation.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2058 Incoming conversation data
(ConvId=conv)
Explanation: The client received an indication
from a server that data had been received for an
active conversation; conv identifies the
conversation on which data was received.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2059 Request directed to unknown
server server
Explanation: The client received a requested
routed to an unknown server; server identifies the
unknown server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2060 Request directed to closing server
server
Explanation: The client received a request
routed to a server which was closing down;
server identifies the closing server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2061 MaxServers limit of number has
been reached
Explanation: The client received a request
routed to a new server but was already
connected to its MaxServers limit; number
indicates the current MaxServers setting.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2062 TR Delete request (SessId=session,
TermId=index, TermName=name)
Explanation: The client received a request to
delete a terminal from an emulator or EPI
application. The session value identifies the
application, the index value gives the EPI
terminal index and the name gives the terminal
name.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2063 TR EXIT detected (SessId=session,
TermId=index, TermName=name)
Explanation: The client detected the special
terminal EXIT transaction code from an emulator
or EPI application. The session value identifies
the application, the index value gives the EPI
terminal index, and the name gives the terminal
name.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2056 CCL2063
Messages 13

CCL2064 CCL2082
CCL2064 TR issue ATI tran (SessId=session,
TermId=index, TermName=name)
Explanation: The client requested an emulator
or EPI application terminal to start an ATI
transaction. The tran value gives the name of the
ATI, the session value identifies the application,
the index value gives the EPI terminal index, and
the name gives the terminal name.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2065 MaxRequests limit of number has
been reached
Explanation: The client received a request for a
new conversation but was already at its
MaxRequests limit; number indicates the current
MaxRequests setting.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2070 MaxBufferSize limit of size
exceeded by incoming data length
length
Explanation: The client received data from a
server that exceeded the MaxBufferSize limit. The
size value indicates the current MaxBufferSize
setting and the length value indicates the length
of the incoming data.
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the value of
MaxBufferSize in the client initialization file to at
least the size of the incoming data.
CCL2079 Failed to put transport message,
retry number number
Explanation: The client has attempted to put a
transport message to a window owned by the
client application. This has failed, the most likely
reason for this is that the message queue
14 CICS Transaction Gateway: CICS Transaction Gateway Messages
associated with the windows client application is
full.
System Action: The message is written to the
trace file if tracing is enabled. The client allows
windows to process messages in the queue and
then tries posting the transport message again, a
number of times.
User Response: Try using SetMessageQueue to
increase the size of the message queue.
CCL2080 Extended request continued with
server server
Explanation: The client continued routing an
extended unit of work request to the named
server. The server value identifies the server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2081 CCIN install response: transaction
not present
Explanation: The server does not support the
CCIN client install transation, this is a normal
response from certain older host CICS servers.
These servers cannot support client 3270 terminal
emulation or user written EPI applications.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2082 CCIN install response: transaction
requires security
Explanation: The server requires a userid and
password to be supplied before it will run the
CCIN client install transaction. If no userid and
password has been made available the client will
prompt for one before retrying the connection to
the server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.

CCL2087I Server server, User ID invalid,
please re-enter
Explanation: The userid entered in the previous
security pop-up panel is not known to the
receiving security system.
System Action: The client displays a pop-up
panel allowing a userid and password to be
re-entered or the request to be cancelled.
User Response: Enter a valid userid and
password to allow the request to be processed by
the server.
CCL2088I Server server, Password invalid,
please re-enter
Explanation: The password entered in the
previous security pop-up panel is incorrect.
System Action: The client displays a pop-up
panel allowing a userid and password to be
re-entered or the request to be cancelled.
User Response: Enter a valid userid and
password to allow the request to be processed by
the server.
CCL2089I Server server, Password expired,
please change
Explanation: The password entered in the
previous security pop-up panel has expired.
System Action: The client displays a pop-up
panel allowing the password to be changed or
the request to be cancelled.
User Response: Enter the expired password, a
new password and confirm the new password to
allow the request to be processed by the server.
CCL2090I Server server, New Password
unacceptable, please re-enter
Explanation: The new password entered in the
previous security pop-up panel is unacceptable
to the receiving security system.
System Action: The client displays a pop-up
panel allowing a new password to be supplied
or the request to be cancelled.
User Response: Enter the expired password, a
new password and confirm the new password to
allow the request to be processed by the server.
CCL2091I New and Confirm Passwords do
not match, please re-enter
Explanation: The new password and confirm
passwords entered in the previous security
pop-up panel do not match.
System Action: The client displays a pop-up
panel allowing a new password to be supplied
or the request to be cancelled.
User Response: Enter the expired password, a
new password and confirm the new password to
allow the request to be processed by the server.
CCL2092 About to display a popup
message
Explanation: A popup message is about to be
displayed on the Client daemon system.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2093 Returned from displaying a
Popup Message
Explanation: The popup message has been
cleared, processing continues.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL2087I CCL2158
CCL2158 Default userid has been set to
spaces.
Explanation: The default userid has been set to
a value which contains only spaces.
System Action: The message is logged, and
processing continues.
User Response: When using connection
security, blank userids and passwords are valid
Messages 15

CCL3001E CCL3009E
only if Usedfltuser is set to YES in the CICS
connection definition.
CCL3001E Errors detected at line number in
file file name
Explanation: Errors were detected at the
specified line in the client initialization file.
System Action: The client terminates.
User Response: Correct the initialization file
and restart the client.
CCL3002E Cannot find client initialization
file file name
Explanation: The specified client initialization
file could not be found.
System Action: The client terminates.
User Response: Ensure that the required
initialization file exists and is correctly specified
when starting the client.
CCL3003E Missing = sign after parameter
parameter
Explanation: An = sign was expected after an
initialization file parameter in the client
initialization file.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3004E Parameter text not recognized
Explanation: An unknown parameter starting
with specified text was encountered in the client
initialization file.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
16 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL3005E Parameter parameter repeated or
misplaced
Explanation: A valid parameter was
encountered in the wrong position in the client
initialization file.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3006E Parameter parameter has invalid
value value
Explanation: A valid parameter had an incorrect
value specified in the client initialization file.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3007E Inconsistent values for parameters
parameter 1 and parameter 2
Explanation: The values of certain parameters
specified in the client initialization file have
dependencies on each other. The values for the
two specified parameters are inconsistent.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3008E Required parameter parameter
missing
Explanation: The specified parameter is missing
from the client initialization file and must be
provided.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3009E Not enough memory for client
initialization
Explanation: There was not enough free
memory to process the client initialization file.

System Action: The client terminates.
User Response: Try altering the values in the
client initialization file to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL3010E Missing driver definition for
protocol protocol
Explanation: The value of the protocol
parameter in a Server section of the client
initialization file must match with the name of a
Driver section. No matching driver definition
was found for the named protocol.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3011E Errors detected while reading file
file name
Explanation: Errors were encountered while
reading the client initialization file.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3012E Duplicate section section
definition
Explanation: A Client, Server, or Driver section
in the client initialization file had the same name
as a previously specified section.
System Action: The client terminates.
User Response: Correct the initialization file
error and restart the client.
CCL3013E Unable to access file file name,
rc=rc
Explanation: Errors were encountered while
accessing file file name.
System Action: The client terminates.
User Response: Change the file permissions
and restart the client.
CCL3010E CCL3105
CCL3102 Inbound GDS data error (gds,
length, size)
Explanation: The client received invalid data
from a server. The data does not have a valid
CICS data stream header. The gds value should
be either 0x12F2 or 0x12FF, the length value gives
the expected data length, and size gives the true
received length.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL3103 Inbound SYNC/ROLL data error
(length, data)
Explanation: The client received invalid data
from a server. The data was not part of a valid
SYNC or ROLLBACK flow. The length values
gives the length of the received data and data
contains the first four bytes.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL3104 Inbound FMH43 header error
(length)
Explanation: The client received invalid data
from a server. The data was not a valid CICS
FMH43 header. The length values gives the
length of the received data.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL3105 Inbound CICS data stream error
(type, value1, value2)
Explanation: The client received invalid data
from a server. The data was not a valid CICS
data stream. The type value indicates which part
of the data contained errors, value1 and value2
further identify the error. This message may be
Messages 17

CCL3106 CCL3112E
received if the server does not support signon
capable terminals.
System Action: The message is written to the
error log and processing continues.
User Response: Use the option to request a
non-signon capable terminal. If the problem
persists, contact your service organization.
CCL3106 Out of memory unpacking CICS
data stream
Explanation: The client was unable to allocate
enough memory to save data from a server.
Normally such data is a COMMAREA associated
with an emulator terminal.
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the values in the
client initialization file, to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL3107 Inbound FMH5 transaction name
incorrect (data)
Explanation: The client received an invalid
transaction attach request from a server. The only
valid transaction name is CRSR, used to start ATI
requests to a terminal. The data value indicates
the requested transaction name.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL3108 Inbound FMH5 header error
(length)
Explanation: The client received invalid data
from a server. The data was not a valid CICS
FHM5 header. The length value gives the length
of the received data.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
18 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL3109E Cannot connect to server server -
client is already installed
Explanation: The client name specified in the
Client section of the initialization file was already
installed on the specified server.
System Action: The server rejects the client’s
installation request.
User Response: Ensure all client names are
unique within the network or specify the name
as ″*″ to enable a suitable unique name to be
generated automatically.
CCL3110E Cannot connect to server server -
server is busy
Explanation: The specified server was busy and
could not process the client installation request.
System Action: The server rejects the client’s
installation request.
User Response: Retry the request sometime
later when the server is not so busy. If the
problem persists contact your server
administrator.
CCL3111E Cannot connect to server server -
server rejected install request
Explanation: The specified server could not
process the client installation request.
System Action: The server rejects the client’s
installation request, server continues processing.
User Response: Examine the client error log
and, if possible, trace information on both the
client and server to determine the cause of the
error.
CCL3112E Cannot connect to server server -
request rejected by server exit
Explanation: A user exit running on the
specified server rejected the request to install the
client definition.
System Action: The server rejects the client’s
installation request, the client continues
processing.

User Response: Check with the server system
administrator to determine why the client
installation request was rejected.
CCL3113 CCIN install request:
ApplId=applid, Codepage=codepage
Explanation: The client invoked the CCIN
system install transaction on a server. The applid
and codepage values indicate the requested client
APPLID and codepage.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3114 CCIN install response:
ApplId=applid, Codepage=codepage,
RC=error
Explanation: The client received the CCIN
system install response from a server. The applid
and codepage values indicate the returned client
APPLID and codepage. The error values are
non-zero if any errors occurred.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3115 CTIN install request:
NetName=name, Model=model,
Codepage=codepage
Explanation: The client invoked the CTIN
terminal install transaction on a server. The name,
model and codepage values indicate the requested
terminal name, model and codepage.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3116 CTIN install response:
NetName=name, TermId=term,
Rc=error
Explanation: The client received the CTIN
terminal install response from a server. The name
and term values indicate the returned terminal
NetName and TermName. The error values are
non-zero if any errors occurred.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3117 PEM verify request: UserId=name
Explanation: The client invoked the password
expiry management (PEM) transaction on a
server to verify a userid and password. The
specified user id is indicated.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3118 PEM change request: UserId=name
Explanation: The client invoked the password
expiry management (PEM) transaction on a
server to change the password of the specified
user id.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3119 PEM response: Rc=error,
CompStatus=value
Explanation: The client received the password
expiry management (PEM) transaction response
from a server. The error value is non-zero if an
error occured. The CompStatus value is set as
follows: 1 = Unknown user id 2=Userid valid,
passwordinvalid3=Useridvalid,password
expired4=Newpasswordunacceptable 5 =
Security function failure 6=Incorrectdata
format
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3113 CCL3119
Messages 19

CCL3120 CCL3228
CCL3120 PEM response data error:
ReqType=Request Type,
ErrorValue=value
Explanation: The client received the password
expiry management (PEM) transaction response
from a server. The data contained in the
corresponding PEM request contained a data
formatting error.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL3121E Cannot connect to server server -
invalid codepage specified
Explanation: The codepage value sent to the
server was rejected.
System Action: The server rejects the client’s
installation request, the client continues
processing.
User Response: If the CCSID parameter has
been specified in CTG.INI, check that the value
specified is valid. Otherwise, check with the
server system administrator to determine why
the codepage value was rejected.
CCL3209 Link to server (link) is no longer
available
Explanation: The client tried to communicate
with a server whose connection is currently
unavailable.
System Action: The message is written to the
error log and processing continues. The server is
ignored.
User Response: If the problem persists, contact
your service organization.
CCL3221 Unable to find link control
structure (link)
Explanation: The client was unable to locate an
internal control structure associated with a
connection to a server.
20 CICS Transaction Gateway: CICS Transaction Gateway Messages
System Action: The message is written to the
error log and processing continues. The server is
ignored.
User Response: If the problem persists, contact
your service organization.
CCL3222 Unable to find conversation
control structure (conv)
Explanation: The client was unable to locate an
internal control structure associated with a server
conversation.
System Action: The message is written to the
error log and processing continues. The
conversation is ignored.
User Response: If the problem persists, contact
your service organization.
CCL3225 Invalid communications event
identifier (event)
Explanation: The client received an invalid
internal event from a communications protocol
driver.
System Action: The message is written to the
error log and processing continues. The event is
ignored.
User Response: If the problem persists, contact
your service organization.
CCL3227 Conversation (conv) isnotinstate
state
Explanation: The client detected a conversation
to a server in an incorrect state.
System Action: The message is written to the
error log and processing continues. The request
is ignored.
User Response: If the problem persists, contact
your service organization.
CCL3228 Unable to find protocol control
structure (name, driver)
Explanation: The client was unable to locate an
internal control structure associated with a

communications protocol driver.
System Action: The message is written to the
error log and processing continues. The driver is
ignored.
User Response: If the problem persists, contact
your service organization.
CCL3229E Cannot load protocol driver driver
Explanation: The specified communications
protocol driver module could not be found or
loaded.
System Action: No communication can take
place using the protocol, the client continues
processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3230 Out of memory creating
communications control structure
Explanation: The client was unable to allocate
enough memory to create an internal control
structure associated with communications.
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the values in the
client initialization file, to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL3231 Comms Load request
(Driver=name)
Explanation: The client communications has
received a request to load a new protocol driver.
The name value indicates the required protocol
driver DLL name.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3232 Comms Load completed
(Driver=name, DrvId=driver,
RC=error)
Explanation: The client completed a request to
load a new protocol driver. The name value
indicates the required protocol driver DLL name,
the driver value indicates the assigned driver
identifier and error indicates any error codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3233 Loading protocol driver
(DLL=fullname)
Explanation: The client wss loading a new
communications protocol driver DLL; fullname
gives the full file system name of the DLL to be
loaded.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3234 Comms Unload completed
(Driver=name, RC=error)
Explanation: The client completed a request to
unload a protocol driver. The name value
indicates the protocol driver DLL name and error
indicates any error codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3235 Freeing protocol driver
(DLL=fullname)
Explanation: The client was freeing a
communications protocol driver DLL; fullname
gives the full file system name of the DLL to be
freed.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3229E CCL3235
Messages 21

CCL3236 CCL3243
CCL3236 Comms Open completed
(Server=name, LinkId=link,
RC=error)
Explanation: The client completed a request to
try to establish a new connection with a server.
The name value indicates the server, the link
value contains the assigned link identifier, and
error indicates any error codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3237 Comms Close completed
(LinkId=link, RC=error)
Explanation: The client completed a request to
close a connection with a server. The link value
identifies the server connection to be closed and
error indicates any error codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3238 Comms Allocate completed
(LinkId=link, ConvId=conv,
RC=error)
Explanation: The client completed a request to
allocate a new conversation with a server.
System Action: The message is written to the
trace file if tracing is enabled. The link value
identifies the server, the conv value contains the
assigned conversation identifier, and error
indicates any error codes.
User Response: None.
CCL3239 Comms Deallocate completed
(ConvId=conv, Reason=reason,
RC=error)
Explanation: The client completed a request to
deallocate a conversation with a server. The conv
value identifies the conversation, the reason and
error values indicate any errors.
System Action: The message is written to the
22 CICS Transaction Gateway: CICS Transaction Gateway Messages
trace file if tracing is enabled.
User Response: None.
CCL3240 Comms Accept completed
(ConvId=conv, RC=error)
Explanation: The client completed a request to
accept a new incoming conversation with a
server. The conv value identifies the conversation
and error indicates any error codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3241 Comms Send completed
(ConvId=conv, RC=error)
Explanation: The client completed a request to
send data over a conversation with a server. The
conv value identifies the conversation and error
indicates any error codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3242 Comms Send request:
Length=length (ConvId=conv)
Explanation: The client communications has
received a request to send data over a
conversation with a server. The conv value
identifies the conversation and length indicates
the length of data to be sent.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3243 Comms Wait completed
(ConvId=conv, RC=error)
Explanation: The client completed a request to
wait for a response over a conversation with a
server. The conv value identifies the conversation
and error indicates any error codes.
System Action: The message is written to the

trace file if tracing is enabled.
User Response: None.
CCL3244 Comms Receive request
(ConvId=conv)
Explanation: The client communications has
received a request to receive data from a
conversation with a server; conv identifies the
conversation.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3245 Comms Receive completed:
Length=length (ConvId=conv,
Reason=reason, RC=error)
Explanation: The client completed a request to
receive data from a conversation with a server.
The conversation remains active. The conv value
identifies the conversation, the length value
contains the length of the data received, and
reason and error indicate any error codes. The
message is followed by the data received.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3246 Comms Complete completed
(ConvId=conv, RC=error)
Explanation: The client completed a request to
finish with data received from a conversation
with a server. The conv value identifies the
conversation and error indicates any error codes.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3247 Error loading DLL fullname
(function, error)
Explanation: The client was unable to load a
communications protocol driver DLL.
System Action: The message is written to the
error log and processing continues. The name of
the failing DLL and the loading function and
error codes are logged.
User Response: Ensure the DLL is available and
correctly named. If the problem persists contact
your service organization.
CCL3248 Comms Unload request
(Driver=name)
Explanation: The client communications has
received a request to unload a protocol driver;
name indicates the protocol driver DLL name.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3249 Comms Open request
(Server=name, Driver=protocol)
Explanation: The client communications has
received a request to try to establish a new
connection with a server. The name value
indicates the server and protocol indicates the
required communications protocol driver.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3250 Comms Close request
(LinkId=link)
Explanation: The client communications has
received a request to close a connection with a
server; link identifies the server connection.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3244 CCL3251
CCL3251 Comms Allocate request
(LinkId=link, Tran=tran)
Explanation: The client communications has
received a request to allocate a new conversation
with a server. The link value identifies the server
Messages 23

CCL3252 CCL3280E
and the tran value gives the name of the
transaction to be attached on the server.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3252 Comms Deallocate request
(ConvId=conv)
Explanation: The client communications has
received a request to deallocate a conversation
with a server; conv identifies the conversation.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3253 Comms Accept request
(ConvId=conv)
Explanation: The client communications has
received a request to accept a new incoming
conversation with a server; conv identifies the
conversation.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3254 Comms Wait request
(ConvId=conv)
Explanation: The client communications has
received a request to wait for a response over a
conversation with a server; conv identifies the
conversation.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3255 Comms Complete request
(ConvId=conv)
Explanation: The client communications has
received a request to finish with data received
from a conversation with a server; conv identifies
the conversation.
24 CICS Transaction Gateway: CICS Transaction Gateway Messages
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3256 Comms Receive completed (last):
Length=length (ConvId=conv,
Reason=reason, RC=error)
Explanation: The client completed a request to
receive data from a conversation with a server.
The conversation has been ended. The conv value
identifies the conversation, the length value
contains the length of the data received, and
reason and error indicate any error codes. The
message is followed by the data received.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3257 Internal CcDrv.Notify returned
return code
Explanation: Data has been received by the
tcpip protocol driver, and the protocol driver
notifies the client of this data. If the notify
completes with return code 3300, then the server
supports conversational pings and a timeout has
occurred. In this case the data received will be
thrown away since the application request has
already timed out.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL3280E Errors occurred while initializing
protocol driver driver
Explanation: The specified communications
protocol driver module reported errors during
startup.
System Action: No communications can take
place using the protocol, the client continues
processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.

CCL3281E Errors occurred while terminating
protocol driver driver
Explanation: The specified communications
protocol driver module reported errors while it
was closing down.
System Action: The error is ignored and the
client continues processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3282E Errors occurred while connecting
to a server using protocol driver
driver
Explanation: The specified communications
protocol driver module reported errors while it
was trying to connect to a server.
System Action: The client cannot communicate
with the server, the client continues processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3283E Errors occurred while
disconnecting from a server using
protocol driver driver
Explanation: The specified communications
protocol driver module reported errors while it
was closing a connection with a server.
System Action: The error is ignored and client
continues processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3284E Errors occurred while starting a
conversation with a server using
protocol driver driver
Explanation: The specified communications
protocol driver module reported errors while it
was starting a new conversation with a
connected server.
CCL3281E CCL3287E
System Action: The request to start the
conversation fails and the client continues
processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3285E Errors occurred while closing a
conversation with a server using
protocol driver driver
Explanation: The specified communications
protocol driver module reported errors while it
was closing a conversation with a connected
server.
System Action: The request to close the
conversation fails and the client continues
processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3286E Errors occurred while sending
data to a server using protocol
driver driver
Explanation: The specified communications
protocol driver module reported errors while it
was sending data over a conversation with a
connected server.
System Action: The request that sent the data
fails and the client continues processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3287E Errors occurred while receiving
data from a server using protocol
driver driver
Explanation: The specified communications
protocol driver module reported errors while it
was receiving data from a conversation with a
connected server.
System Action: The request that required the
data fails and the client continues processing.
Messages 25

CCL3288E CCL3310
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3288E Errors occurred while
communicating with a server
using protocol driver driver
Explanation: The specified communications
protocol driver module reported errors while it
was communicating or trying to communicate
with a server.
System Action: The request that initiated the
communications fails and the client continues
processing.
User Response: Examine the client error log
and, if possible, trace information to determine
the cause of the error.
CCL3299 Internal communications error
(function, error)
Explanation: An internal client communications
function failed.
System Action: The message is written to the
error log and the client terminates. The function
name and error code are logged.
User Response: If the problem persists, contact
your service organization.
CCL3300 Before EPI Calltype:
Explanation: The client EPI application is about
to issue EPI call EPI Calltype
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.
User Response: None.
CCL3301 After EPI Calltype: Event: Event,
rc=rc
Explanation: The client EPI application has
issued EPI call EPI Calltype which ended with
return code rc. Event Event also occurred.
System Action: The message is written to the
26 CICS Transaction Gateway: CICS Transaction Gateway Messages
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.
User Response: None.
CCL3302 EPI event information,Idx=Idx
Explanation: This trace entry is issued for a
number of reasons during EPI processing. The
text of the message will describe the particular
instance. Idx is the EPI terminal index.
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.
User Response: None.
CCL3303 Before: extended call information
Explanation: This trace entry contains more
information relating to the EPI call detailed in a
previous CCL3300 trace entry for this task.
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace and
ApiTraceLevel = 2 is specified in the client
initialization file.
User Response: None.
CCL3304 After: extended call information
Explanation: This trace entry contains more
information relating to the EPI call detailed in a
previous CCL3301 trace entry for this task.
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace and
ApiTraceLevel = 2 is specified in the client
initialization file.
User Response: None.
CCL3310 Before ECI Calltype: UOW
Token=UOW token
Explanation: The client ECI application is about
to issue ECI call ECI Calltype
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.

User Response: None.
CCL3311 After ECI Calltype: rc=rc, UOW
Token=UOW token
Explanation: The client ECI application has
issued ECI call ECI Calltype, which completed
with return code rc.
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.
User Response: None.
CCL3312 Notification type for call ECI
Calltype
Explanation: The client ECI application has
been notified using notification type for ECI call
ECI CallType.
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.
User Response: None.
CCL3313 Before function name:
Explanation: The client application is about to
issue the call function name
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.
User Response: None.
CCL3314 After function name: rc=rc
Explanation: The client application has issued
the call function name, which completed with
return code rc.
System Action: The message is written to the
trace file if tracing is enabled and ApiTrace is
specified in the client initialization file.
User Response: None.
CCL3311 CCL3402
CCL3315 Unexpected comms error (internal
return codes rc1 , rc2)
Explanation: An network communications error
occurred.
System Action: The message is written to the
error log and the client continues. The internal
return codes provide information for use by IBM
service groups.
User Response: If the problem persists, contact
your service organization.
CCL3400 Unable to find an LDAP server
(rc=rc, Reason=reason)
Explanation: Trying to find the LDAP server
using DNS.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the existing configuration file.
User Response: To use LDAP contact your
system administrator to set up their DNS
correctly. Otherwise disable LDAP by using the
environment variable or the /z optiononthe
command line.
CCL3401 Unable to retrieve user credentials
Explanation: Trying to get the users credentials
for use with LDAP.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the existing configuration file.
User Response: To rectify this problem it is
recommended you reinstall the product.
CCL3402 Unable to retrieve LDAP
password (rc=rc, Reason=reason)
Explanation: To retrieve encrypted LDAP
password from the registry.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the existing configuration file.
User Response: The user must have a user ID
Messages 27

CCL3403 CCL4401
set up to talk to the LDAP server. Check that this
has been done.
CCL3403 Unknown LDAP error (rc=rc,
Reason=reason)
Explanation: An unknown error has occurred
while using LDAP.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the existing configuration file.
Look at the reason for more guidance.
User Response: None.
CCL3404 Binding error to LDAP server
(rc=rc, Reason=reason)
Explanation: An error occured while trying to
bind to the LDAP server.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the existing configuration file.
Look at the reason for more guidance.
User Response: None.
CCL3405 Unbinding error to LDAP server
(rc=rc, Reason=reason)
Explanation: An error occurred while trying to
bind to the LDAP server.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the new configuration file.
Look at the reason for more guidance.
User Response: None.
CCL3406 Trying to read LDAP entry error
(rc=rc, Reason=reason,
entry=baseDN)
Explanation: The client tried to read an LDAP
entry, but was unable too.
System Action: This message is written to the
trace file, if tracing is enabled. Look at the reason
for more guidance.
28 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: None.
CCL3407 Entry does not exist (rc=rc,
Reason=reason, entry=baseDN)
Explanation: The client tried to test for
existence of an LDAP entry.
System Action: This message is written to the
trace file, if tracing is enabled. Look at the reason
for more guidance.
User Response: None.
CCL3408 Unable to find any configuration
entry in LDAP server
Explanation: An error occurred while trying to
find a configuration entry on the LDAP server,
but was unable to find any.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the existing configuration file.
User Response: None.
CCL3409 Unable to write to file
Explanation: An error occurred while trying to
write the new configuration file.
System Action: The message is written to the
log file if the error occurs. The system will
continue by using the existing configuration file.
User Response: Check the security settings on
the ctg.ini file.
CCL4401 TCP/IP not available
Explanation: The TCP/IP protocol driver cannot
issue TCP/IP calls on this system. TCP/IP may
not be installed or may not be active on the
system.
System Action: The message is written to the
error log and processing continues.
User Response: Alter the system configuration
to try to activate or install TCP/IP. If the
problem persists, contact your service personnel.

CCL4402 TCP/IP out of memory for data
buffers
Explanation: The TCP/IP protocol driver could
not allocate enough memory to create the
internal data buffers.
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the values in the
client initialization file, to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL4403 TCP/IP (to server) no resources
available: RC=error
Explanation: The TCP/IP protocol driver could
not create a TCP/IP socket. The server value
identifies the server and the error value identifies
the TCP/IP error code.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL4404 TCP/IP (to server) unable to
resolve name: RC=error
Explanation: The TCP/IP protocol driver could
not resolve a server host IP name. The server
value identifies the server and the error value
gives the TCP/IP error code.
System Action: The message is written to the
error log and processing continues.
User Response: Ensure the server IP name or
address is correct and can be resolved by the
local name server. If the problem persists contact
your service organization.
CCL4405 TCP/IP (to server) out of memory
for control blocks
Explanation: The TCP/IP protocol driver could
not allocate enough memory to create the
internal control structures; server identifies the
server.
CCL4402 CCL4408
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the values in the
client initialization file, to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL4406 TCP/IP (to server) send failed:
RC=error
Explanation: The TCP/IP protocol driver could
not send data to a server. The server value
identifies the server and the error value gives the
TCP/IP error code.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL4407 TCP/IP (to server) connect failed:
RC=error
Explanation: The TCP/IP protocol driver could
not connect to a server. The server value
identifies the server and the error value gives the
TCP/IP error code.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL4408 TCP/IP (to server) recv failed:
RC=error
Explanation: The TCP/IP protocol driver could
not receive data from a server. The server value
identifies the server and the error value gives the
TCP/IP error code.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
Messages 29

CCL4409 CCL4415
CCL4409 TCP/IP (to server) error starting
listener
Explanation: The TCP/IP protocol driver could
not start an internal listener function; server
identifies the server.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL4410 TCP/IP requires WINSOCK
vrequired (vfound installed)
Explanation: The TCP/IP protocol driver for
Windows requires a WINSOCK DLL of at least
version required, however version found was
found to be installed. The required and found
values indicate the version of WINSOCK
required and found respectively.
System Action: The message is written to the
error log and processing continues.
User Response: Ensure your TCP/IP product
provides a suitable level of the WINSOCK DLL
and the system is correctly configured. If the
problem persists contact your service
organization.
CCL4411 TCP/IP (to server) send data:
Length=length
Explanation: The TCP/IP protocol driver was
about to send data to a server. The server value
identifies the server and the length value contains
the length of the data to be sent. This message is
followed by the data to be sent, which consists of
the client data and a TCP/IP protocol header.
The total data flow may be sent in several pieces.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4412 TCP/IP (to server) receive data:
Length=length
Explanation: The TCP/IP protocol driver
received data from a server. The server value
30 CICS Transaction Gateway: CICS Transaction Gateway Messages
identifies the server and the length value contains
the length of the data received. This message is
followed by the data received, which consists of
the data returned to the client and a TCP/IP
protocol header. The total data flow may be
received in several pieces.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4413 TCP/IP (to server) address=ipaddr,
port=port, socket=socket
Explanation: The TCP/IP protocol driver has
established a connection to a server. The server
value identifies the server. The ipaddr, port, and
socket values give the server’s IP address, the
server’s port number, and the socket used,
respectively.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4414 TCP/IP (to server) link failed:
RC=error
Explanation: The TCP/IP link failed. The server
value identifies the server and the error value
gives the TCP/IP error code.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: If the problem persists, contact
your service organization.
CCL4415 TCP/IP (to server) abend received:
RC=sense code
Explanation: The transaction failed. The server
value identifies the server and the sense code
value gives the FMH7 sense data.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: If the problem persists, contact
your service organization.

CCL4416 TCP/IP (to server) Waiting for
Connect Timer
Explanation: The ConnectTimeOut value in the
Server Section of the initialisation file has been
set to a value other than 0 (the default), and the
connection timer is running.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4417 TCP/IP (to server) TimeOut on
Connect: Rc=error
Explanation: The timer for ConnectTimeOut has
expired and the attempt to connect to the Server
is being terminated.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4418 TCP/IP (to server) Before Send
data Length= length
Explanation: A TCP/IP send is about to be
performed.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4419 TCP/IP (to server) Before Wait
CCB address = address
Explanation: The TCP/IP wait routine has been
entered.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4420 TCP/IP (to server) AfterWaitCCB
address = address, rc= return code
Explanation: The TCP/IP wait routine has been
exitted.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4421 TCP/IP (to server) Need to receive
data of length length, bytes bytes
available
Explanation: The TCP/IP receive processing
information detailing how much data is to
received.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4422 TCP/IP (to server) Before recv for
length length
Explanation: Before the TCP/IP recv is issued.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4423 TCP/IP (to server) After recv got
length length
Explanation: After the TCP/IP recv was issued
and successfully completed.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4424 TCP/IP (to server) Bad recv error
number error
Explanation: The TCP/IP recv got a bad return
code.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4416 CCL4425
CCL4425 TCP/IP Allocation for memory
block failed rc = rc
Explanation: During TCP/IP processing a
memory allocation failed.
Messages 31

CCL4426 CCL4602
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4426 TCP/IP (to server) Errorwhen
attempting to send good ping
response, rc= rc
Explanation: An error occurred when
attempting to send a good ping response.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4427 TCP/IP (to server) Received
unknown ping
Explanation: Received a flow that looks like a
ping but cannot be interpretted by the existing
criteria.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4428 TCP/IP (to server) ErrorinTCP
processing rc = rc
Explanation: At the end of the receive
processing loop, there is an error.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4429 TCP/IP Finished processing
inbound data,rc=rc,
available=bytes
Explanation: This is the end of the processing
loop. For the receive thread to be restarted, rc
needs to be zero and bytes needstobezeroor
positive. If the recv thread is not started, tcp
receives will not occur.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
32 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL4430 TCP/IP (to server) Bad send error
number error
Explanation: The TCP/IP send got a bad return
code.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL4499 TCP/IP (to server) datatobe
received overflows buffer
Explanation: The TCP/IP protocol driver
received more data than its buffer space could
hold. The server value identifies the server, the
data is discarded.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL4601 Memory allocation of display
buffer failed
Explanation: There was insufficient free
memory for the client SNA protocol driver to
retrieve LU 6.2 information from the APPC
provider.
System Action: The SNA protocol driver is not
initialized.
User Response: Free up some memory and
retry.
CCL4602 Memory allocation of receive
buffer pool failed
Explanation: There was insufficient free
memory for the client SNA protocol driver to
receive data from any servers.
System Action: The SNA protocol driver is not
initialized.
User Response: Free up some memory and
retry.

CCL4603 Memory allocation of send buffer
failed
Explanation: There was insufficient free
memory for the client SNA protocol driver to
send data to any servers.
System Action: The SNA protocol driver is not
initialized.
User Response: Free up some memory and
retry.
CCL4605 Begin thread to handle inbound
ATI requests failed
Explanation: Creation of thread, to handle
inbound allocate requests from ATI to client
terminals, failed.
System Action: The SNA protocol driver is not
initialized.
User Response: Contact your system
administrator.
CCL4606 Netname partner LU name has
invalid length for an alias name
Explanation: The specified partner LU name in
the NetName parameter in your client
initialization file has an invalid length for this
SNA protocol driver and LUAliasNames
parameter setting. The maximum length of an
alias name is 8 characters, the minimum length is
1.
System Action: The connection to the partner
LU is not started.
User Response: Refer to the Administration
book to determine whether or not this SNA
protocol driver requires the use of alias names.
Correct the NetName and/or LUAliasNames
parameters in the client initialization file and
retry.
CCL4607 Netname partner LU name has
invalid length for a fully
qualified name
Explanation: The specified partner LU name in
the NetName parameter in your client
CCL4603 CCL4610
initialization file has an invalid length for this
SNA protocol driver and LUAliasNames
parameter setting. The maximum length of a
fully qualified name is 17 characters
(********.********). The minimum length is 1.
System Action: The connection to the partner
LU is not started.
User Response: Refer to the Administration
book to determine whether or not this SNA
protocol driver supports fully qualified names.
Correct the NetName and/or LUAliasNames
parameters in the client initialization file and
retry.
CCL4608 Memory allocation of link data
block failed for server connection
Explanation: There was insufficient free
memory for the client SNA protocol driver to
open a link to the specified server.
System Action: The client continues.
User Response: Free up some memory and
retry.
CCL4609 Retrieval of LU 6.2 information
for server connection failed, APPC
return code primary RC, secondary
RC
Explanation: The client SNA protocol driver
was unable to open a link to the specified server
because retrieval of LU6.2 information from the
APPC provider failed. The APPC DISPLAY verb
failed with the specified return code.
System Action: The client continues.
User Response: Contact your system
administrator.
CCL4610 LU 6.2 information for server
connection not all returned on
retrieval
Explanation: The client SNA protocol driver
was unable to open a link to the specified server
because not all of the LU6.2 information could be
obtained from the APPC provider.
Messages 33

CCL4611 CCL4617
System Action: The client continues.
User Response: Contact your system
administrator.
CCL4611 Local LU LU name is not defined
Explanation: The client SNA protocol driver
was unable to open any link using this LU
because it is not defined to IBM Communications
Manager/2.
System Action: The client continues.
User Response: Define the LU to IBM
Communications Manager/2 or correct the
LocalLUName parameter in your client
initialization file and retry.
CCL4612 Partner LU partner LU name is not
defined
Explanation: The client SNA protocol driver
was unable to open any link using this partner
LU because it is not defined to IBM
Communications Manager/2.
System Action: The client continues.
User Response: Define the partner LU to IBM
Communications Manager/2 or correct the
NetName parameter in your client initialization
file and retry.
CCL4613 Communication Subsystem not
loaded, APPC return code primary
RC
Explanation: APPC could not execute the verb
because Communications Manager had not
started APPC. Either Communications Manager
has not been started or it has not been
configured correctly for the application.
System Action: The client continues.
User Response: Start Communications Manager
if it is not active. If the necessary APPC profiles
are not configured, configure them and restart
Communications Manager.
34 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL4614 Open connection to server failed
with APPC return code primary
RC, secondary RC
Explanation: The APPC verb TP_STARTED
failed with the specified return code. The
connection to the specified server has not been
started.
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4615 Close connection to server failed
with APPC return code primary
RC, secondary RC
Explanation: The APPC verb TP_ENDED failed
with the specified return code.
System Action: The client connection to the
specified server is closed.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4616 Memory allocation of
conversation data block failed for
server connection
Explanation: There was insufficient free
memory for the client SNA protocol driver to
start a conversation with the specified server.
System Action: The client continues.
User Response: Free up some memory and
retry.
CCL4617 No contention-winner sessions
free
Explanation: APPC could not allocate a
conversation because no free sessions were
available.
System Action: The client continues.
User Response: Wait until one or more existing

conversations have finished and retry.
CCL4618 SNASVCMG or CPSVCMG is not
a valid mode name, APPC return
code primary RC, secondary RC
Explanation: An attempt was made to allocate a
client conversation in SNASVCMG or CPSVCMG
sessions mode. These are not valid modes.
System Action: The client continues.
User Response: Change the Modename
parameter in your client initialization file and
retry.
CCL4619 Mode name mode name is not
configured, APPC return code
primary RC, secondary RC
Explanation: The specified mode has not been
defined.
System Action: The client continues.
User Response: Check whether the mode has
been configured, and the spelling of the
ModeName parameter in your client initialization
file.
CCL4620 Allocate session to server failed
with APPC return code primary
RC, secondary RC
Explanation: The APPC verb ALLOCATE failed
with the specified return code. A conversation
with the specified server has not been started.
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4621 Deallocate session to server failed
with APPC return code primary
RC, secondary RC
Explanation: The APPC verb DEALLOCATE
failed with the specified return code.
System Action: The client continues.
CCL4618 CCL4625
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4622 Begin thread to receive data for
ATI conversation with server
failed
Explanation: A client thread could not be
created to process the queue holding inbound
attach requests; _beginthread failed.
System Action: The SNA protocol driver is not
initialized.
User Response: Contact your system
administrator.
CCL4623 Begin thread to receive data for
conversation with server failed
Explanation: A client thread could not be
created to receive data from the server for the
current conversation; _beginthread failed.
System Action: The conversation is deallocated.
User Response: Contact your system
administrator.
CCL4624 Inbound ATI initialisation failed
with return code return code
Explanation: An attempt to allocate resources
for inbound allocate requests from ATI to client
terminals has failed.
System Action: The client continues but all
inbound request processing is terminated.
User Response: Check SNA configuration for
ATI Side Information Profile entry.
CCL4625 Error processing inbound ATI
request, all ATI processing
terminated
Explanation: An error occurred during an
inbound ATI request.
System Action: The client continues but all
inbound request processing is terminated.
Messages 35

CCL4626 CCL4633
User Response: Contact your system
administrator.
CCL4626 Attach Manager stopped, APPC
return code primary RC, secondary
RC
Explanation: The client received an inbound
ATI attach request but the receive allocate failed
because the attach manager was stopped.
System Action: The inbound allocate request is
rejected.
User Response: Start the attach manager.
CCL4629 Receive_allocate for ATI request
failed with APPC return code
primary RC, secondary RC
Explanation: The APPC verb
RECEIVE_ALLOCATE failed with the specified
return code.
System Action: The inbound allocate request is
rejected.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4630 Send data to server failed with
APPC return code primary RC,
secondary RC
Explanation: The APPC verb SEND_DATA
failed with the specified return code.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
36 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL4631 Receive data from server failed
with APPC return code primary
RC, secondary RC
Explanation: The APPC verb
RECEIVE_AND_POST failed with the specified
return code.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4632 Error receiving data from server,
APPC what_received return
parameter is APPC return code
Explanation: An APPC RECEIVE returned an
unexpected data_received or conversation
status_received indicator.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4633 Memory allocation of receive
buffer failed
Explanation: There was insufficient free
memory for the client SNA protocol driver to
receive data on the current conversation.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Free up some memory and
retry the transaction.

CCL4634 Create semaphore for
ReceiveAndPost failed, return
code operating system return code
Explanation: An attempt to set post semaphore
for receiving conversation data failed.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Contact your system
administrator.
CCL4635 Allocate session to server failed,
TP name TP name unknown,
APPC return code primary RC,
secondary RC
Explanation: The server rejected the incoming
attach because the client or client application
specified a TP name that the server did not
recognize.
System Action: The client continues.
User Response: Ensure that the specified TP is
installed on the server.
CCL4636 Allocate session to server failed
with APPC return code primary
RC, secondary RC. Retry
Explanation: APPC could not allocate a
conversation but retrying without intervention
may succeed. APPC was probably unable to
activate a link or a session.
System Action: The client continues.
User Response: Retry the operation. If retrying
does not succeed, see your APPC Programming
Reference information for further information or
contact your system administrator.
CCL4637 Allocate session to server failed
with APPC return code primary
RC, secondary RC; no retry
Explanation: APPC could not allocate a
conversation and intervention is required to
correct the problem.
CCL4634 CCL4640
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
information or contact your system
administrator.
CCL4638 Prepare to receive data from server
failed with APPC return code
primary RC, secondary RC
Explanation: The APPC verb
PREPARE_TO_RECEIVE failed with the specified
return code.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4639 Receive data from server failed
with APPC return code primary
RC, secondary RC
Explanation: The APPC verb
RECEIVE_IMMEDIATE failed with the specified
return code.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4640 Error receiving data from server,
APPC what_received return
parameter is APPC return code
Explanation: An APPC RECEIVE returned an
unexpected data_received or conversation
status_received indicator.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
Messages 37

CCL4641 CCL4649
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4641 Send data and deallocate to server
failed with APPC return code
primary RC, secondary RC
Explanation: The APPC verb SEND_DATA with
DEALLOCATE type failed with the specified
return code.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4642 Invalid number of parameters
defined for TP program EXE name
Explanation: The TP program was invoked
because of an inbound allocate request but the
IBM Communications Manager definition for the
TP program has an invalid number of
parameters defined.
System Action: The inbound allocate request is
rejected.
User Response: Refer to the Administration
book, correct the TP definition, and retry.
CCL4643 Invalid TP name parameter
defined for TP program EXE name
Explanation: The TP program was invoked
because of an inbound allocate request but the
IBM Communications Manager definition for the
TP program has an invalid TP name parameter
defined.
System Action: The inbound allocate request is
rejected.
User Response: Refer to the Administration
book, correct the TP definition, and retry.
38 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL4646 APPC send data: Length=length
Explanation: This is trace data sent to the server
by the client SNA protocol driver.
System Action: None.
User Response: None.
CCL4647 APPC receive data: Length=length
Explanation: This is trace data received from
the server by the client SNA protocol driver.
System Action: None.
User Response: None.
CCL4648 Receive data from server
unsuccessful after partial data
received, APPC return code
primary RC, secondary RC
Explanation: The APPC verb
RECEIVE_IMMEDIATE failed with the specified
return code after some data had already been
received.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Try altering the SnaRetryCount
parameter in the client initialization file and
retry. Refer to the Administration book.
CCL4649 Post on receipt of data from server
failed with APPC return code
primary RC, secondary RC
Explanation: The APPC verb
POST_ON_RECEIPT failed with the specified
return code.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.

CCL4650 Partner LU name netname is not
fully qualified
Explanation: The partner LU name specified in
the NetName parameter in your client
initialization file was not qualified by the SNA
network name (NETID). The format is
NETID.LU_NAME.
System Action: The connection to the partner
LU is not started.
User Response: If using real LU names, correct
the NetName parameter and retry. If using alias
LU names, set the LUAliasNames parameter to Y
and retry.
CCL4651 Allocate session to server
unsuccessful after number retry
attempts, APPC return code
primary RC, secondary_RC
Explanation: The attempt to allocate a session
to the specified server was unsuccessful after the
number of retries specified in your client
initialization file.
System Action: The client continues.
User Response: Contact your system
administrator.
CCL4652 Conversation with server failed,
APPC return code primary RC,
retry
Explanation: A temporary failure prematurely
ended the conversation.
System Action: The client continues.
User Response: Retry the operation. If retrying
does not succeed, see your APPC Programming
Reference information for further information, or
contact your system administrator.
CCL4653 Conversation with server failed,
APPC return code primary RC, no
retry
Explanation: A permanent failure prematurely
ended the conversation. The link to the server
has probably failed.
CCL4650 CCL4656
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
information or contact your system
administrator.
CCL4654 CNOS for mode mode sessions to
server failed, APPC return code
primary RC, secondary RC
Explanation: The APPC verb CNOS failed with
the specified return code. The connection to the
specified server has not been started.
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
information, or contact your system
administrator.
CCL4655 Partner LU server maximum
session limit is zero, APPC return
code primary RC, secondary RC
Explanation: The APPC verb CNOS failed
because the local maximum session limit of the
partner LU is 0. The connection to the specified
server has not been started.
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
the particular error, or contact your system
administrator.
CCL4656 Mode mode not recognized by
partner LU, APPC return code
primary RC, secondary RC
Explanation: The APPC verb CNOS failed as
the partner LU does not recognize the specified
mode name. The connection to the specified
server has not been started.
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
the particular error, or contact your system
administrator.
Messages 39

CCL4657 CCL4663
CCL4657 SNA Server has no active services
Explanation: The client SNA protocol driver
was unable to open a link to the specified server
because SNA server has no active services.
System Action: The client continues.
User Response: Activate the relevant service via
SNA Server Administration or contact your
system administrator.
CCL4658 WinAPPCStartup failed with
return code Windows APPC RC
Explanation: The client SNA protocol driver
was unable to open a link to the specified server
because it failed to register itself with the
currently installed Windows APPC
implementation.
System Action: The client continues.
User Response: Contact your system
administrator.
CCL4659 Local LU LU name is not defined
on an active service/node
Explanation: The client SNA protocol driver
was unable to open any link using this LU
because it is not defined on an active SNA
service/node.
System Action: The client continues.
User Response: Activate the relevant service
SNA service or define the LU to an active SNA
service/node or correct the LocalLUName
parameter in your client initialization file and
retry.
CCL4660 Partner LU partner LU name is not
defined in a connection with local
LU LU name
Explanation: The client SNA protocol driver
was unable to open any link using this partner
LU because it is not defined in a connection with
the specified local LU on an active SNA
service/node.
System Action: The client continues.
40 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: Define a connection between
the specified local and partner LUs on an active
SNA service/node or correct the NetName
parameter in your client initialization file and
retry.
CCL4661 SNA stack component not loaded
or terminated, APPC return code
primary RC
Explanation: APPC could not execute the verb
because a component of the product providing
the SNA transport could not be loaded or
terminated whilst processing the verb.
System Action: The client continues.
User Response: Contact your system
administrator.
CCL4662 Load of SNA stack library DLL
name failed, return code Windows
return code
Explanation: LoadLibrary failed, the client
could not load the specified dynamic link library.
System Action: The client SNA protocol driver
is not loaded.
User Response: Install and configure one of the
supported products for SNA transport, if this has
not already been done, and ensure that the DLL
is in the LoadLibrary search path; then retry. Or
contact your system administrator.
CCL4663 Load of client driver DLL name by
TP program EXE name failed with
return code Windows return code
Explanation: LoadLibrary failed, the client
inbound ATI TP could not load the specified
dynamic link library.
System Action: The ATI request is rejected.
User Response: Contact your system
administrator.

CCL4664 TP program EXE name failed with
an internal error, return code value
Explanation: The client inbound ATI TP failed
due to an internal error.
System Action: The ATI request is rejected.
User Response: Contact your system
administrator.
CCL4665 TP program not available on
server, APPC return code primary
RC, secondary RC, retry
Explanation: APPC could not start a remote TP
program retrying without intervention may
succeed.
System Action: The client continues.
User Response: Retry the operation. If retrying
does not succeed, see your APPC Programming
Reference information for further information or
contact your system administrator.
CCL4666 TP program not available on
server, APPC return code primary
RC, secondary RC, no retry
Explanation: APPC could not start a remote TP
program and intervention is required to correct
the problem. The remote server is probably not
available.
System Action: The client continues.
User Response: Ensure the remote server is
available and if the problem persits ee your
APPC Programming Reference information for
further information or contact your system
administrator.
CCL4667 SNA Server not configured for
inbound requests, APPC return
code primary RC, secondary RC
Explanation: The APPC verb
RECEIVE_ALLOCATE failed as SNA Server has
not been correctly configured to receive inbound
ATI requests.
System Action: The client continues.
CCL4664 CCL4671
User Response: If inbound ATI request
processing is required, refer to the
Administration book on how to configure SNA
Server.
CCL4668 SNA node not started, APPC
return code primary RC
Explanation: The SNA node has not been
started.
System Action: The client continues.
User Response: Start the SNA node and retry
the operation.
CCL4669 Real LU names not supported by
current client SNA driver.
Explanation: The client SNA driver specified in
the client initialization file does not support LU
names specified as real names.
System Action: The connection to the server is
not started.
User Response: Specify the local and partner
LU names in the client initialization file as alias
names, set the LUAliasNames parameter to Y and
retry.
CCL4670 Communications subsystem
abended, APPC return code
primary RC, secondary RC
Explanation: Either the APPC provider has
abended or has not been configured properly on
the client machine.
System Action: The connection to the server is
not started.
User Response: Check the configuration of the
APPC provider on the CICS client machine. If
using NWSAA v2.2, check that the NDS
configuration for the NWSAA client is correct.
CCL4671 LU alias LU alias name is not
defined
Explanation: The specified LU alias is not
defined in the APPC provider.
Messages 41

CCL4672 CCL4677
System Action: The connection to the server is
not started.
User Response: If using alias LU names, define
the LU alias and retry. If using real LU names,
set the LUAliasNames parameter to N in the client
initialisation file and retry.
CCL4672 Partner LU alias LU alias name or
mode mode name is unknown,
APPC return code primary RC,
secondary RC
Explanation: If using real LU names, the
specified mode is not defined. If using alias LU
names, either the partner LU alias supplied in
the Netname parameter in the client initialisation
file is not defined, or the mode is not defined, in
the APPC provider.
System Action: The connection to the server is
not started.
User Response: Check that the parameters in
the client initialisation match the definitions in
the APPC provider.
CCL4673 Conversation with server failed,
APPC return code primary RC,
secondary RC
Explanation: There has been a failure to allocate
a conversation or to receive data from the
specified server. The link to the server has
probably failed.
System Action: The client continues.
User Response: Refer to your APPC
Programming Reference information for further
information or contact your system
administrator.
CCL4674 TP program TP name abended on
server server, APPC return code
primary RC
Explanation: The specified TP program abended
on the given server. If the TP program is CTIN,
then this may be because the server has been
recycled since running CCIN.
System Action: The client continues. If the TP
42 CICS Transaction Gateway: CICS Transaction Gateway Messages
program is CTIN, the client will attempt to
reconnect to the server and retry the request.
User Response: Contact your system
administrator.
CCL4675 Wait on semaphore for
ReceiveAndPost failed, return
code operating system return code
Explanation: An attempt to wait on a
semaphore for conversation data, after successful
completion of the receive verb, failed.
System Action: The client sends a deallocate
abend to the server to terminate the
conversation.
User Response: Contact your system
administrator.
CCL4676 Protocol driver failed to notify
client of a data event, return code
internal return code
Explanation: The protocol driver’s attempt to
notify the client of a data event failed.
System Action: The protocol driver sends a
deallocate abend to the server to terminate the
conversation.
User Response: Contact your system
administrator.
CCL4677 Callback for
RECEIVE_AND_POST for
unknown convid APPC conv_id
received
Explanation: The protocol driver’s callback
function was called for the specified
conversation, but it was not in the list of
conversations for which a RECEIVE_AND_POST
call had been made.
System Action: The event is ignored.
User Response: Contact your system
administrator.

CCL5800 TCP62: TCP/IP not available
Explanation: TCP/IP is not started and may not
have been configured or installed.
System Action: The message is written to the
error log and processing continues, but the
TCP62 protocol is unavailable for use.
User Response: Make sure TCP/IP is active
before starting the TCP62 protocol driver.
CCL5801 TCP62: WINSOCK required or later
required(found installed)
Explanation: The TCP62 protocol driver for
Windows requires a WINSOCK DLL of at least
version required, however version found was
found to be installed. The required and found
values indicate the version of WINSOCK
required and found respectively.
System Action: The message is written to the
error log and processing continues, but the
TCP62 protocol is unavailable for use.
User Response: Ensure your TCP/IP product
provides a suitable level of the WINSOCK DLL
and the system is correctly configured. If the
problem persists contact your service
organization.
CCL5802 TCP62: Out of memory for data
buffers
Explanation: The TCP62 protocol driver could
not allocate enough memory to create the
internal data buffers.
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the values in the
client initialization file, to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL5803 TCP62: Out of memory for control
blocks
Explanation: The TCP62 protocol driver could
not allocate enough memory to create the
internal control structures.
CCL5800 CCL5807
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the values in the
client initialization file, to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL5804 TCP62: Failure to create
semaphores
Explanation: An attempt to create a system
semaphore failed.
System Action: The message is written to the
error log and processing continues, but the
TCP62 protocol is unavailable for use.
User Response: Contact your system
administrator.
CCL5805 TCP62: Unexpected TCP/IP return
code error on socket socknum
Explanation: The TCP62 protocol driver
detected an error return code from TCP/IP. The
error value gives the TCP/IP error code.
System Action: The message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organization.
CCL5806 TCP62: Failure to create threads
Explanation: An attempt to begin a thread (or
pthread) failed.
System Action: The message is written to the
error log and processing continues, but the
TCP62 protocol is unavailable for use.
User Response: Contact your system
administrator.
CCL5807 TCP62: Invalid MODENAME
modename
Explanation: An attempt was made to allocate a
client conversation in SNASVCMG or CPSVCMG
sessions mode. These are not valid modes.
Messages 43

CCL5808 CCL5814
System Action: The client continues.
User Response: Change the modename
parameter in your client initialization file and
retry.
CCL5808 TCP62: Netname partner LU name
has an invalid length for a fully
qualified name
Explanation: The specified partner LU name in
the NetName parameter in your client
initialization file has an invalid length for the
TCP62 protocol driver. The maximum length of a
fully qualified name is 17 characters
(********.********). The minimum length is 1.
System Action: The connection to the partner
LU is not started.
User Response: Correct the NetName parameter
in your client initialization file and retry.
CCL5809 TCP62: Partner LU name partner
LU name is not fully qualified
Explanation: The partner LU name specified in
the NetName parameter in your client
initialization file was not qualified by the SNA
network name (NETID). The format is
NETID.LU_NAME.
System Action: The connection to the partner
LU is not started.
User Response: Correct the NetName parameter
and retry.
CCL5810 TCP62: No contention-winner
sessions free
Explanation: TCP62 could not allocate a
conversation because no free sessions were
available.
System Action: The client continues.
User Response: Wait until one or more existing
conversations have finished and retry.
44 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL5811 TCP62: Unresolved host name host
IP name, TCP/IP Rc=error
Explanation: The TCP62 protocol driver could
not resolve a server host IP name. The error value
gives the TCP/IP error code.
System Action: The message is written to the
error log and processing continues.
User Response: Ensure the server IP name or
address is correct and can be resolved by the
local name server. If the problem persists contact
your service organization.
CCL5812 TCP62: Server server name does not
recognise mode mode name
Explanation: The APPC verb CNOS failed as
the partner LU does not recognize the specified
mode name. The connection to the specified
server has not been started.
System Action: The client continues.
User Response: Correct the ModeName
parameter in your client initialization file and
retry, or contact your system administrator.
CCL5813 TCP62: Session session id failed to
connect
Explanation: The TCP62 protocol driver could
not connect to a server. The session id value
contains the server name.
System Action: The message is written to the
error log and processing continues.
User Response: Check that TCP62 is using the
same TCP/IP port as the server. Check with your
administrator that the server is available. If the
problem persists, contact your service
organization.
CCL5814 TCP62: Session session id connect
timed out
Explanation: The TCP62 protocol driver could
not connect to a server. The session id value
contains the server name.
System Action: The message is written to the

error log and processing continues.
User Response: Check with your administrator
that the server is available. If the problem
persists, contact your service organization.
CCL5815 TCP62: Session session id
MPTNCONN rejected,
Rc=primary,secondary, sense
data=sense data
Explanation: The TCP62 protocol driver could
not connect to a server. The session id value
contains the server name. There may be MPTN
primary and secondary error codes or SNA sense
data.
System Action: The message is written to the
error log and processing continues.
User Response: Look up the SNA sense data in
the SNA Formats book for an explanation. Check
with your administrator that the server is
available. If the problem persists, contact your
service organization.
CCL5816 TCP62: The current user does not
have the required permission
Explanation: On UNIX systems the TCP62
protocol driver must have root permissions to
use TCP/IP port numbers less than 1024.
System Action: The message is written to the
error log and processing continues, but the
TCP62 protocol is unavailable for use.
User Response: Contact your system
administrator for guidance on whether to run
with root permissions or to use an alternative
TCP/IP port number.
CCL5817 TCP62: Session session id remote
node inactive
Explanation: The TCP62 protocol driver lost
contact with a server which did not respond to
inactivity polling. The session id value contains
the server name.
System Action: The message is written to the
error log and processing continues.
CCL5815 CCL5820
User Response: Check with your administrator
that the server is available. If the problem
persists, contact your service organization.
CCL5818 TCP62: TCP/IP port port already in
use
Explanation: The TCP62 protocol driver can not
be started because it is configured to use TCP/IP
port number port which is in use by another
program.
System Action: The message is written to the
error log and processing continues, but the
TCP62 protocol is unavailable for use.
User Response: Find the program (e.g.
PCOMM) that is running and configured to use
the same TCP/IP port number. Either stop that
program, or configure it or the TCP62 protocol
driver to use a different port.
CCL5819 TCP62: Out of memory for
peek-ahead buffer
Explanation: The TCP62 protocol driver could
not allocate enough memory to create the
internal peek-ahead buffer.
System Action: The message is written to the
error log and processing continues.
User Response: Try altering the values in the
client initialization file, to provide the client with
a larger free memory pool or to reduce the
overall memory requirements.
CCL5820 TCP62: Attempt to open server
server1 which is a duplicate of
server2
Explanation: Server definitions must differ in
either local LU name, network name, or mode.
System Action: The message is written to the
error log and processing continues.
User Response: Existing applications that use
different server names to send requests to the
same CICS region can continue to work if a user
exit is coded to redirect requests. A sample user
exit that does this is provided; see the samples
documentation for more details.
Messages 45

CCL5834 CCL6504I
CCL5834 TCP62: Link close processing did
not complete successfully
Explanation: The processing to close the link to
the server did not complete within the expected
time.
System Action: This message is written to the
error log, and processing continues.
User Response: It is recommended that you
restart the client. This ensures that the previous
connection has been terminated. If the problem
persists, contact your service organization.
CCL5835 TCP62: Socket closed with
outstanding data
Explanation: The processing to close the link to
the server closed a TCPIP socket that had
outstanding data to be sent.
System Action: This message is written to the
error log and processing continues.
User Response: If the problem persists, contact
your service organisation.
CCL6500I No command line options have
been specified.
Explanation: The Gateway daemon is starting
using either the default configuration settings, or
those set with the configuration tool. Default
settings are used when none have been set with
the configuration tool.
System Action: A Gateway console session is
started.
User Response: For help on the startup options,
enter ctgstart -?
CCL6501I Command line options have been
specified.
Explanation: The Gateway daemon is starting
using options specified from the command
prompt.
System Action: Options specified on the
command line will override those specified using
the configuration tool.
46 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: For help on the startup options,
enter ctgstart -?
CCL6502I Initial ConnectionManagers = n1,
Maximum ConnectionManagers =
n2, Initial Workers = n3,
Maximum Workers = n4, tcp:
Port= n5.
Explanation: n1 ConnectionManager threads
will be created initially. A maximum of n2
ConnectionManager threads will be allowed. One
ConnectionManager thread is needed for each
connected client program. n3 Worker threads will
be created initially. A maximum of n4 Worker
threads will be allowed. One Worker thread is
needed for each in progress request. The tcp/ip
protocol handler will accept connections on port
n5.
System Action: The Gateway daemon has
started using these values.
User Response: For information only.
CCL6503I Starting with tracing messages on.
Explanation: Extra tracing messages have been
enabled.
System Action: Information passing between
the Gateway daemon and the Java client will be
recorded.
User Response: For help on the startup options,
enter ctgstart -?
CCL6504I Starting with debugging messages
on.
Explanation: Debugging messages have been
enabled.
System Action: Debugging information passing
between the Gateway and Java client will be
recorded.
User Response: For information only.

CCL6505I Successfully created the initial
ConnectionManager and Worker
threads.
Explanation: ConnectionManager and Worker
threads handle network connections and requests
from or replies to Java clients.
System Action: ConnectionManager will handle
network connections from a particular Java
client, the Worker thread will execute requests
from it.
User Response: For information only.
CCL6506I Client connected. [{0}] - {1}
Explanation: A client program connected. The
connection is being handled by
ConnectionManager {0}. The connection was
made with protocol characteristics {1}.
System Action: If an existing client program is
in execute mode, put the connected client
program in a queue. If there is no client program
in execute mode, execute the connected client
program.
User Response: For information only.
CCL6507I Client disconnected. [{0}] - {1}
Explanation: A client program has
disconnected. The connection was being handled
by ConnectionManager {0}. The connection was
made with protocol characteristics {1}.
System Action: If there is still work in progress,
the ConnectionManager waits for the length of
the closetimeout period for in-progress requests
to complete.
User Response: For information only.
CCL6508I Type Q or - to stop the CICS
Transaction Gateway.
Explanation: Type either character, followed by
the Enter key.
System Action: The Gateway daemon will stop.
User Response: For information only.
CCL6505I CCL6514I
CCL6510I TCP/IP hostnames will not be
shown.
Explanation: The -nonames command line
option was specified. This is useful in
environments where a TCP/IP DNS is not
available.
System Action: Any displayed TCP/IP
addresses will not be resolved to TCP/IP
hostnames.
User Response: For information only.
CCL6511I ThreadManager created {0} {1}(s).
Explanation: The ThreadManager created {0}
thread(s) of type {1}
System Action: Create {0} threads of type {1}
User Response: Use the configuration tool to
specify the number of threads that can be
created.
CCL6512I Waiting to receive a request. [{0}]
Explanation: ConnectionManager {0} is waiting
for an inbound request.
System Action: When a request is received,
ConnectionManager will allocate a worker
thread.
User Response: For information only.
CCL6513I About to receive remainder of a
request. [{0}]
Explanation: A header has been received for a
request of type {0}.
System Action: Retrieve information on request
to execute the remainder of request.
User Response: For information only.
CCL6514I Accepting work request. [{0}] [{1}]
Explanation: Worker thread {0} has accepted a
request from ConnectionManager {1}.
System Action: Execute CICS request.
Messages 47

CCL6515I CCL6522I
User Response: For information only.
CCL6515I Finished work request. [{0}]
Explanation: Worker thread {0} has successfully
completed a request.
System Action: Send CICS reply to client.
User Response: Check CICS reply from
Gateway.
CCL6516W Outstanding work in progress.
[{0}] [{1}]
Explanation: A client has disconnected from
ConnectionManager {0}, but {1} work requests
are still in progress.
System Action: A ConnectionManager will not
become available to handle another connection
until the work has been finished.
User Response: Wait for requests to finish.
CCL6517I All outstanding work has been
finished. [{0}]
Explanation: Where {0} specifies the
ConnectionManager.
System Action: Wait for next client program
connection or stop gateway.
User Response: Either run a new client
program or quit the gateway.
CCL6518W Cleanups for previous requests
are outstanding. [{0}] [{1}]
Explanation: A client has disconnected from
ConnectionManager {0}, but {1} requests which
require completion are still outstanding.
System Action: The ConnectionManager will
attempt to clean up the allocated resources.
User Response: For information only.
48 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6519I Attempts have been made to clean
up all unfinished requests.
Explanation: The Gateway has finished trying
to cleanup allocated resources for the
disconnected client.
System Action: None.
User Response: For information only.
CCL6520I This request has registered a
cleanup object. [{0}]
Explanation: A Request has been received
which has provided an associated cleanup object.
System Action: The ConnectionManager stores
this cleanup object in case it needs to cleanup the
resource on behalf of the client application.
User Response: For information only.
CCL6521I This request has updated an
already registered cleanup object.
[{0}]
Explanation: A Request has been received
which has provided an associated cleanup object,
but one already exists for this allocated resource.
System Action: The ConnectionManager
replaces the stored cleanup object with this new
one.
User Response: For information only.
CCL6522I This is a cleanup request,
corresponding entry in the
cleanup table removed. [{0}]
Explanation: A request has been received from
an application which cleans up an allocated
resource.
System Action: The ConnectionManager
removes its stored cleanup object for that
resource.
User Response: For information only.

CCL6523I About to execute work request.
[{0}]
Explanation: Where {0} specifies the Worker
thread.
System Action: Executing request.
User Response: For information only.
CCL6524I Successfully started handler for
the {0}: protocol.
Explanation: Where {0} specifies the protocol
type.
System Action: Gateway started with {0}
protocol handler.
User Response: For information only.
CCL6525E Unable to start handler for the {0}:
protocol. [{1}]
Explanation: Where {0} specifies the protocol
type, and {1} specifies the cause of the error. The
most likely cause is that the protocol handler is
attempting to listen on a TCP/IP port that is
already in use.
System Action: Gateway forced to stop because
of {0} protocol handler error.
User Response: Check if protocol or port is
available and supported by running gateway.
CCL6526I Parameters passed to {0}: protocol
handler = {1}.
Explanation: The parameters, {1}, defined in the
CTG initialization file have been passed to the {0}
protocol handler.
System Action: Gateway started with {0}
protocol handler = {1}.
User Response: For information only.
CCL6527I Using {0} class to provide security
to {1}.
Explanation: The {0} ServerSecurity class is
being used on connection {1}.
CCL6523I CCL6531W
System Action: Gateway is using secured
connection.
User Response: For information only.
CCL6528W Outstanding work still in
progress. [{0}] [{1}]
Explanation: A client has disconnected from
ConnectionManager {0}, with work requests in
progress. {1} requests have failed to finish within
a reasonable time.
System Action: The ConnectionManager marks
itself as available again.
User Response: For information only.
CCL6529W Unable to send reply to client.
[{0}]
Explanation: The Gateway worker thread {0}
was unable to send the reply to the client. This
could be because the client was disconnected.
System Action: System action is not required.
User Response: Check if client is still running.
CCL6530I Disconnecting idle client. [{0}]-{1}
Explanation: ConnectionManager disconnected
the client at {1}, which had been idle for longer
then the idletimeout value specified in the
configuration file.
System Action: System action is not required.
User Response: For information only.
CCL6531W Unable to disconnect idle client -
work still in progress. [{0}]-{1}
Explanation: The client at {1} has been idle for
too long, but there are still work requests in
progress on its behalf.
System Action: ConnectionManager did not
disconnect the client.
User Response: For information only.
Messages 49

CCL6532I CCL6547W
CCL6532I Disconnecting non-responsive
client. [{0}]-{1}
Explanation: The client at {1} did not respond to
a PING before the next was due to be sent.
System Action: The client will be disconnected.
User Response: For information only.
CCL6533E Unable to read the ctg.ini file. [{0}]
Explanation: Where {0} specifies the reason for
the failure.
System Action: The Gateway stops; it will not
run without an ini file.
User Response: Check that CTG.INI exists in
the bin directory, or that the ini file specified
through the CICSCLI environment variable
exists. Run the configuration tool if necessary to
create an ini file.
CCL6534I Using a worker timeout of {0}
milliseconds.
Explanation: The worker thread timeout is set
to {0} ms.
System Action: System action is not required.
User Response: For information only.
CCL6535I Using a close timeout of {0}
milliseconds.
Explanation: The closedown timeout is set to {0}
ms.
System Action: System action is not required.
User Response: For information only.
CCL6536I Generic ECI reply calls will not
be allowed.
Explanation: Generic ECI reply calls will not be
allowed.
System Action: System action is not required.
User Response: For information only.
50 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6537I Security classes will be required
for all connections on all
protocols.
Explanation: Security is set on all protocols for
all connections.
System Action: System action is not required.
User Response: For information only.
CCL6544E Port {0} is invalid.
Explanation: The port number specified for the
TCPIP protocol handler is outside the range 0 to
65535.
System Action: The TCPIP protocol handler
does not start.
User Response: Specify a valid TCPIP port
number within the allowed range.
CCL6545E [{0}] {1}:EXCI error. Function Call
= {2}, Response = {3}, Reason = {4},
Subreason field-1 = {5}, subreason
field-2 = {6} CTG_Rc={7}
Explanation: An EXCI call within a JNI native
method failed. Where {0} = a number used
internally by IBM service groups. {1} = name of
the CTG function which issued the ECI call. {2} =
a number representing EXCI call type.
{3},{4},{5},{6} = error codes from the failing EXCI
call. {7} = the return code that will be send to the
CTG application.
System Action: Check the EXCI documentation
for source of error.
User Response: For information only.
CCL6547W The Gateway will display
symbolic TCPIP hostnames in
console messages
Explanation: This might affect system
performance.
System Action: The Gateway will continue
processing.
User Response: Set NONAMES=ON in the
CTG.INI file to avoid this. Refer to the CICS

Transaction Gateway Administration book for
further details.
CCL6550E Unable to listen on requested port
Explanation: Gateway is unable to recognize
port number.
System Action: System action is not required.
User Response: Check valid port number,
protocol and server name.
CCL6551E Unable to create requested
ConnectionManager and worker
threads.
Explanation: Usually this means that the system
is running low on resources.
System Action: System action is not required.
User Response: Reduce the number of
ConnectionManager and worker threads initially
created.
CCL6552E Error whilst accepting a
connection from {0}. Connection
closed. [{1}]
Explanation: A connection was accepted from
{0}, but a problem of type {1} occurred.
System Action: Unable to connect.
User Response: Check error code.
CCL6553E Error reading request. [{0}]
Explanation: Where {0} specifies the
ConnectionManager thread.
System Action: Unable to execute request.
User Response: Check if connection is still
available.
CCL6554E Error in native method. [{0}]
Explanation: Where {0} specifies the Worker
thread.
System Action: System action is not required.
CCL6550E CCL6559E
User Response: For information only.
CCL6555E Error writing reply [{0}]
Explanation: Where {0} specifies the Worker
thread.
System Action: Unable to write reply.
User Response: Check if connection is still
available.
CCL6556E Error copying request on local
Gateway.
Explanation: A problem has occurred in the
local Java Gateway support.
System Action: Unable to copy request on local
Gateway.
User Response: Check if Gateway is configured
to use local protocol.
CCL6557E Error whilst executing request.
[{0}]
Explanation: An error occurred while
processing request with name [{0}]
System Action: System action is not required.
User Response: Check that request is valid.
CCL6558E No protocol handlers started
successfully.
Explanation: Gateway cannot access any
protocol handlers.
System Action: If no protocol handlers can be
started, the Gateway will exit.
User Response: Check the CTG initialization
file for protocol handlers; uncomment the
protocol handle you want.
CCL6559E Unexpected exception occurred
[{0}]
Explanation: An exception of type [{0}]
occurred.
System Action: System action is not required.
Messages 51

CCL6560E CCL6581E
User Response: For information only.
CCL6560E Unable to accept request of type
{0}. [{1}]
Explanation: ConnectionManager {1} has
received a request {0} but failed to load the
required class file to execute the request.
System Action: Gateway exits and displays
error message.
User Response: Make sure that the {0} class is
in the CLASSPATH of the Gateway process.
CCL6561E Unable to use {0} class to provide
security to {1}.
Explanation: The {0} class could not be
successfully loaded to provide security to the
connection from {1}.
System Action: The connection will be closed.
User Response: Make sure that the {0} class is
in the CLASSPATH of the Gateway process.
CCL6562E Connection to {0} rejected due to
insufficient ConnectionManagers.
Explanation: A connection was accepted from
{0}, but a ConnectionManager did not become
available in time.
System Action: The connection was rejected.
User Response: Increase the maximum number
of ConnectionManagers.
CCL6563E {0} protocol handler exited
unexpectedly. [{1}]
Explanation: The {0} protocol handler exited
due to problem {1}.
System Action: Gateway exits and displays
error message.
User Response: Check error code.
52 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6569E Unable to open file {0}
Explanation: File with name {0} could not be
opened.
System Action: System action is not required.
User Response: Check that file is not in use or
read-only.
CCL6574I Connection logging has been
disabled
Explanation: The CICS Transaction Gateway
will not write messages to the log when a client
application connects to, or disconnects from, the
gateway daemon.
System Action: System action is not required.
User Response: To enable connection logging,
select the Log client connections and disconnections
check box in the configuration tool, or set
CONNECTIONLOGGING=ON in the
configuration file, CTG.INI.
CCL6580E The parameter {0} in the ini file is
unrecognized or invalid
Explanation: An unknown parameter starting
with specified text was encountered in the
gateway initialization file.
System Action: The gateway terminates.
User Response: Correct the initialization file
error and restart the gateway. The configuration
tool can be used to correct a badly-formed
initialization file.
CCL6581E The Gateway cannot continue
Explanation: An error was detected.
System Action: The Gateway daemon
terminates.
User Response: Examine any other messages
and the gateway error log to determine the cause
of the error.

CCL6582E The command line option {0} is
unrecognized or invalid
Explanation: An unknown or invalid option
starting with specified text was encountered on
the command line.
System Action: The gateway terminates and
displays help.
User Response: Restart the gateway with a
correct command line option.
CCL65XXW Unable to find message. [{0}]
Explanation: The message appropriate for this
error code cannot be found.
System Action: Display the number of the
message.
User Response: Find the appropriate message
by searching for its number in this message file.
CCL6601I Request specific trace {0}.
Explanation: A historical message.
System Action: System action is not required.
User Response: For information only.
CCL6602I GatewayRequest type = {0}, flow
version = {1}, flow type = {2},
Gateway return code = {3}, length
of data following the header = {4}.
Explanation: Information from current request.
System Action: Execute request.
User Response: For information only.
CCL6650E Unable to connect to the Gateway.
Explanation: Client application unable to
connect to gateway.
System Action: Client request unable to start.
User Response: Check if Gateway is running; if
client application has specified the correct
parameters to connect to the gateway.
CCL6582E CCL6655E
CCL6651E Unable to connect to the Gateway
[address={0}, port={1}] [{2}]
Explanation: Where {0} specifies the Gateway
TCP/IP address, {1} specifies the TCP/IP port
and {2} specifies the cause of the error.
System Action: Client request unable to start.
User Response: Check error code.
CCL6652E Unable to start the Gateway
listener.
Explanation: Client application could not start
the Gateway listener.
System Action: Close this JavaGateway
instance.
User Response: Check that Gateway is correctly
configured.
CCL6653E Unable to flow request to the
Gateway; this JavaGateway
instance has been closed.
Explanation: The Gateway is unreachable.
System Action: Close this JavaGateway
instance.
User Response: Check if the connections to the
Gateway still exist.
CCL6654E An error occurred while the
Gateway was closing. [{0}]
Explanation: Where {0} specifies the cause of
the error.
System Action: Close the Gateway.
User Response: Check error code.
CCL6655E There was an error reading the
reply. [{0}]
Explanation: Where {0} specifies the cause of
the error.
System Action: Unable to read the reply.
User Response: Check error code.
Messages 53

CCL6656E CCL6664E
CCL6656E Flow did not contain the correct
eyecatcher. Fatal Error.
Explanation: Network connection did not
contain the correct identifier.
System Action: Connection closed.
User Response: For information only.
CCL6657E Invalid CICS Transaction Gateway
address specified.
Explanation: The Gateway URL was incorrectly
specified.
System Action: Unable to connect to Gateway
at this address.
User Response: Check Gateway is running and
address is right.
CCL6658E Local Gateway support has been
terminated.
Explanation: Attempts have been made to use
the local Gateway support after the
LocalJavaGateway.terminate method has been
called.
System Action: Unable to make further requests
to this gateway.
User Response: For information only.
CCL6659E In use Local Gateways currently
exist.
Explanation: The LocalJavaGateway.terminate
method has been called while local Gateways are
still in use.
System Action: Wait for requests to finish.
User Response: For information only.
CCL6660E Error copying reply. [{0}]
Explanation: Where {0} specifies the cause of
the error.
System Action: Unable to copy reply.
User Response: Check error code.
54 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6661E Cannot change JavaGateway
properties when the JavaGateway
instance is open.
Explanation: A call to a JavaGateway.set
method has been made, after the JavaGateway
has been opened.
System Action: System action is not required.
User Response: Close JavaGateway instance.
CCL6662E This JavaGateway instance is still
open.
Explanation: This JavaGateway instance is still
open in the client application.
System Action: System action is not required.
User Response: Close this JavaGateway
instance.
CCL6663E Cannot open a JavaGateway
instance when no protocol has
been specified.
Explanation: No protocol classes have been
requested by the client application.
System Action: Unable to make further requests
to this instance.
User Response: Check if client application
specifies a valid protocol parameter.
CCL6664E Unable to load relevant class to
support the {0} protocol.
Explanation: The relevant class could not be
found.
System Action: Unable to create JavaGateway
instance.
User Response: If the protocol {0} is xyz, then
the required class is called xyzJavaGateway.
Ensure that this can be found by your client
program.

CCL6665E This JavaGateway instance has
been closed.
Explanation: The JavaGateway instance was
closed by the client application.
System Action: Unable to make a further
request to this instance.
User Response: Start new JavaGateway
instance.
CCL6666E Unable to flow request to the
Gateway. [{0}]
Explanation: Where {0} specifies the cause of
the error.
System Action: Unable to make further request
to this instance.
User Response: Check error code.
CCL6667E Error writing request. [{0}]
Explanation: Where {0} specifies the cause of
the error.
System Action: Unable to write further requests
to this instance.
User Response: Check error code.
CCL6668E Initial handshake flow failed. [{0}]
Explanation: Caused by {0}
System Action: Unable to make initial
handshake; hence unable to make requests.
User Response: Check error code.
CCL6669E Cannot open JavaGateway. Must
specify both client-side and
server-side security classes.
Explanation: Server application needs security.
System Action: Unable to make requests
because of lack of security.
User Response: Specify both client and server
sides security classes.
CCL6665E CCL6687E
CCL6670E Exception occurred in the
Gateway. [{0}]
Explanation: Where {0} specifies the cause of
the error.
System Action: System action is not required.
User Response: Check error code.
CCL6671E This JavaGateway instance has yet
to be opened.
Explanation: The client application has not
opened a new JavaGateway instance yet.
System Action: System action is not required.
User Response: Open JavaGateway instance
before making requests.
CCL6686E Keyring specified but case does
not match, or cfwk.zip not on
classpath
Explanation: the SSLight implementation for
SSL was selected, but either cfwk.zip was not on
the class path, or a keyring was specified and the
name of the class was correct and it was found,
but the case did not match, so the class cannot be
loaded.
System Action: Either the SSL or HTTPS
protocol will fail to start on the server or the
client application will fail to open a Java
Gateway using SSL
User Response: Ensure cfwk.zip is specified on
the classpath or that you have entered the
keyring class correctly ensuring the case is
identical to the keyring class filename.
CCL6687E Keyring was tampered with, or
password was incorrect.
Explanation: Unable to import keyring.
System Action: System action is not required.
User Response: Ensure correct keyring class
and password has been provided.
Messages 55

CCL6688I CCL6696I
CCL6688I Unknown JSSE Version.
Explanation: Unable to detect JSSE version
strings.
System Action: System action is not required.
User Response: Information only no action
required.
CCL6689I JSSE Package information.
Explanation: Version information relating to
JSSE Libraries.
System Action: System action is not required.
User Response: Information only no action
required.
CCL6690I After JNI {0}
Explanation: A JNI native method call has just
completed. Where {0} is the name of the JNI call.
System Action: System action is not required.
User Response: For information only.
CCL6691I Before JNI {0} : TermIndex={1}
Explanation: The CTG is about to call a JNI
native method. Where {0} is the name of the JNI
call and {1} is the terminal index number
parameter passed to the call.
System Action: System action is not required.
User Response: For information only.
CCL6692I Before JNI {0} : TermIndex={1},
Transid={2}
Explanation: The CTG is about to call a JNI
native method. Where {0} is the name of the JNI
call, {1) is the terminal index number to be
passed to the call and {2} is the transaction id.
System Action: System action is not required.
User Response: For information only.
56 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6693I After JNI {0} : Rc={1},
LUW/TermIndex={2}
Explanation: A JNI native method call has just
completed. Where {0} is the name of the JNI call
and {1} is the return code from the call. {2} may
either represent a LUW token or a terminal index
returned by the call depending on what type of
call was made.
System Action: System action is not required.
User Response: For information only.
CCL6694I Before JNI {0} : Server={1}
NetName={2}
Explanation: The CTG is about to call a JNI
native method. Where {0} is the name of the JNI
call,{1} is the name of the server and {2} is the
NetName to be passed to the JNI call.
System Action: System action is not required.
User Response: For information only.
CCL6695I Before JNI {0} : Server={1},
Program={2},
Commarea.Length={3},
ExtendMode={4}, LUW={5}.
Explanation: The CTG is about to call a JNI
native method. Where {0} is the name of the JNI
call and parameters {1} to {5} are ECI parameters
to be passed to the JNI call.
System Action: System action is not required.
User Response: For information only.
CCL6696I After JNI {0} : Rc={1}
Explanation: A JNI native method call has just
completed. Where {0} is the name of the JNI call
and {1} is the return code from the call.
System Action: System action is not required.
User Response: For information only.

CCL6697I Before JNI {0}
Explanation: The CTG is about to call a JNI
native method. Where {0} is the name of the JNI
call.
System Action: System action is not required.
User Response: For information only.
CCL6702I CICS Request: Successfully
loaded native library.
Explanation: Native library for environment
loaded successfully.
System Action: System action is not required.
User Response: For information only.
CCL6703E CICS Request: Load of native
library failed {0}.
Explanation: Where {0} specifies the Java error.
System Action: Unable to load native library.
User Response: Check if native library is
available.
CCL6704I BMS Map Converter
Explanation: The BMS Map Converter is a
utility that generates Java Map classes from BMS
definition files.
System Action: System action is not required.
User Response: For information only.
CCL6705E {0} is not a valid AID key
Explanation: The exit key parameter indicated
was not a valid AID value. Valid AID keys are
enter, clear, PF1 - 24, and PA1 - 3.
System Action: Unable to execute command.
User Response: Check if AID key is valid.
CCL6706I Classes will be created in package
{0}.
Explanation: When the BMS Map Converter
generates classes, a package statement will be
included, where the name of the package is {0}.
System Action: System action is not required.
User Response: For information only.
CCL6707I ScreenHandler will be generated.
Explanation: A ScreenHandler bean will be
generated for this screen.
System Action: Generating ScreenHandler for
screen.
User Response: For information only.
CCL6708I Use this command to generate
Map classes from BMS Map files.
Explanation: This command generates Map
classes from BMS Map files.
System Action: System action is not required.
User Response: For information only.
CCL6709I Arguments:
bmsfile1
bmsfile2 ..
Explanation: This help will be displayed if the
BMS Map Converter is invoked without
arguments.
System Action: Exit BMS Map Converter and
display arguments accepted.
User Response: Enter valid arguments.
CCL6710I Processing file {0} ...
CCL6697I CCL6710I
Explanation: The BMS Map Converter has
begun processing the file {0}.
System Action: BMS Map Converter is
processing this BMS Map.
User Response: For information only.
Messages 57

CCL6714W CCL6732I
CCL6714W CICS Request: Cics_Rc {0} not
recognised.
Explanation: CICS Server return code {0} is not
valid.
System Action: System action is not required.
User Response: Check if Cics_Rc is valid.
CCL6716E CICS Request: Error in
initialization. [{0}]
Explanation: Where {0} specifies the Java error.
System Action: CICS Request revolted.
User Response: Check the Java error.
CCL6717E CICS Request: An attempt to
convert from a C byte array to a
Java String failed.
Explanation: The codepage specified for the
conversion was {0}.
System Action: A CICS Request attempted to
convert between a C byte array and a Java
String. The codepage being used for the
conversion was {0}.
User Response: Check user codepage.
CCL6718E CICS Request: Error. [{0}]
Explanation: Where {0} specifies the error.
System Action: CICS Request revolted.
User Response: Check error.
CCL6719E CICS Request: Java default
character encoding not obtained.
[{0}]
Explanation: An attempt was made to obtain
the Java default character encoding. {0} specifies
the Java error.
System Action: System action is not required.
User Response: Check the return Java error.
58 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6726I ECIRequest: ECI_BACKOUT
request, Cics_Rc = {0}, Luw_Token
={1}.
Explanation: CICS Transaction back out.
System Action: CICS Server returns to the
status it was before the last request.
User Response: Check Cics_Rc, if it is not 0
then check CICS Server and CICS Client.
CCL6730I ECIRequest: Commarea_Length
limited to length of Commarea.
Explanation: Commarea_Length set to the
length of Commarea specified; usually this is
caused by user-defined Commarea being larger
than the Commarea specified.
System Action: Set Commarea_Length to length
of specified Commarea.
User Response: Reduce User-defined
Commarea.
CCL6731W ECIRequest: This call type may
return a reply intended for
another Java client.
Explanation: Either Call_Type ECI_GET_REPLY
or Call_Type ECI_GET_REPLY_WAIT have been
used. These types of call should be used with
caution since they will return the next reply,
which may be intended for another Java client.
System Action: System action is not required.
User Response: Use ECI_GET_REPLY and
ECI_GET_REPLY_WAIT call types with caution.
CCL6732I ECIRequest: The array containing
the status bytes is null. The
ConnectionType, CicsServerStatus
and CicsClientStatus will be set to
their defaults.
Explanation: No status information has been
returned, so the status fields will be set to their
defaults.
System Action: System action is not required.
User Response: For information only.

CCL6733W ECIRequest: The Commarea
outbound length is greater than
Commarea_Length.
Explanation: The amount of data sent from the
Java client to the CICS Transaction Gateway, is
greater than the size of the Commarea given to
CICS.
System Action: System action is not required.
User Response: Specify Larger Commarea.
CCL6734W ECIRequest: The Commarea
inbound length is greater than
Commarea_Length.
Explanation: The amount of data sent to the
Java client from the CICS Transaction Gateway, is
greater than the size of the Commarea given to
CICS.
System Action: System action is not required.
User Response: Specify larger Commarea.
CCL6735I ECIRequest: Call_Type = {0},
Server = {1}, Extend_Mode =
ECI_STATE_IMMEDIATE.
Explanation: Trace message for ECIRequest.
System Action: System action is not required.
User Response: For information only.
CCL6736E ECIRequest: Message Qualifier is
invalid, outside of range -32767 to
32767
Explanation: An invalid message qualifier
parameter has been provided.
System Action: None.
User Response: Correct the value passed for
message qualifier in the method invocation.
CCL6749E ESIRequest: Userid, Password or
Server Name too long
Explanation: Either the Userid, Password or
Server Name entered is longer than required.
System Action: System action is not required.
User Response: Re-enter the correct Userid,
Password or Server name.
CCL6755E EPIRequest: size field limited to
data.length.
Explanation: The size field may not exceed the
length of the data array.
System Action: System action is not required.
User Response: Specify larger data array.
CCL6762W termIndex: 0xFFFF is invalid for
calls that are not to a local
Gateway.
Explanation: Unless using a local Gateway, it is
invalid to attempt to get an event without
specifying a termIndex, since you may obtain
events intended for other terminal resources.
System Action: System action is not required.
User Response: Specify a termIndex.
CCL6770E ECIRequest: Invalid Call_Type.
Explanation: Invalid call type passed to
ECIRequest
System Action: System action is not required.
User Response: Check call type.
CCL6733W CCL6772E
CCL6771E ECIRequest: Commarea outbound
length is negative.
Explanation: Commarea outbound length must
always be a positive integer.
System Action: Could not create a Commarea
outbound length of this size; default length is set.
User Response: Check if Commarea outbound
length is a positive integer.
CCL6772E ECIRequest: eci_timeout value is
negative.
Explanation: eci_timeout can only be 0 or a
positive integer.
Messages 59

CCL6774E CCL6782E
System Action: Could not set ECI timeout;
default timeout is set.
User Response: Check if eci_time is a positive
integer.
CCL6774E No JavaGateway or EPIGateway
instance has been associated with
this terminal
Explanation: An attempt to connect a terminal
failed as no JavaGateway or EPIGateway
instance has been associated with that terminal
instance.
System Action: None.
User Response: Create and Configure a
JavaGateway or EPIGateway instance and use
the appropriate methods or constructors to
associate this instance with the instance of the
terminal.
CCL6775E Your created terminal cannot use
these extended connect methods,
as it is not an extended terminal
Explanation: An attempt to use the extended
Connect Methods on a terminal has failed. The
Extended Connect methods can only be used on
extended terminal instances.
System Action: None.
User Response: Use the standard connect
method or create an extended terminal instance
if you wish to use the extended connect
methods.
CCL6776E CicsCpRequest: Unable to convert
the CICS code page to a Java
Encoding. [{0}]
Explanation: An attempt to convert a CICS code
page to a Java format, (for example, 850 to
Cp850), failed. {0} is the Java error.
System Action: System action is not required.
User Response: Check the Java error and the
CICS Code page.
60 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6777E Security Exception. Return code
{1} from {0} call.
Explanation: Return code {1} was received
when attempting to invoke a security type
method {0}
System Action: None.
User Response: Look up the return code to
determine the cause of failure.
CCL6779E Cannot find equivalent CSid for
Encoding
Explanation: A Java encoding was specified for
a terminal, but no equivalent host CCSid is
known for this encoding.
System Action: None.
User Response: Check the documentation for
the list of allowed Java encodings that have
equivalent CCSid values.
CCL6780E EPIRequest: Invalid Call_Type.
Explanation: Invalid call type passed to
EPIRequest.
System Action: System action is not required.
User Response: Check call type.
CCL6781E EPIRequest: Invalid event.
Explanation: Invalid event passed.
System Action: System action is not required.
User Response: Check event.
CCL6782E EPIRequest: Invalid termIndex:
0xFFFF.
Explanation: It is invalid to attempt to get an
event without specifying a termIndex, since you
may obtain events intended for other terminal
resources.
System Action: System action is not required.
User Response: Specify a termIndex.

CCL6783E EPIRequest: termIndex {0} does
not exist.
Explanation: Where {0} is the invalid termIndex.
System Action: System action is not required.
User Response: Check that termIndex is
available and unique to this connection.
CCL6784E EPIRequest: termIndex {0} belongs
to another connection.
Explanation: Where {0} is the invalid termIndex.
System Action: System action is not required.
User Response: Check that termIndex is unique
to this connection.
CCL6785E EPIRequest: EPI Initialization
failed. [{0}]
Explanation: Where {0} is the error.
System Action: Exit application.
User Response: For information only.
CCL6786I There are no free terminals
available.
Explanation: The maximum number of
terminals for this application has been reached.
System Action: Stop starting new transactions.
User Response: Wait for free terminal.
CCL6787E Exception [{0}] occurred while
attempting to load classes from
the path: {1}″
Explanation: An exception occurred while
screen handler beans where being loaded from
the path specified. Possible causes are: the
classpath is incorrect, a screen handler bean did
not have a public constructor , a file or directory
could not be accessed.
System Action: System action is not required.
User Response: Check if classpath exist and
classes are available.
CCL6783E CCL6792E
CCL6788E Exception [{0}] occurred while
attempting to load the class: {1}
Explanation: An exception occurred while the
specified class was being loaded. Possible causes
are: the class could not be found, the class did
not have a public constructor.
System Action: System action is not required.
User Response: Check exception and that class
is available and has a public constructor.
CCL6789E An exception has occurred: {0}
Explanation: Where {0} is the exception.
System Action: System action is not required.
User Response: Check where exception has
occurred.
CCL6790E Too much data received from
CICS.
Explanation: More data was returned by CICS
than could be handled.
System Action: System action is not required.
User Response: For information only.
CCL6791E Internal error - terminal state
invalid.
Explanation: An internal error has occurred.
The terminal state is incorrect.
System Action: System action is not required.
User Response: For information only.
CCL6792E Null transaction ID parameter
passed to Terminal.send.
Explanation: If a transaction ID parameter is
passed to send, it must be a valid string.
System Action: System action is not required.
User Response: Check if a valid transaction ID
is given.
Messages 61

CCL6793E CCL6801I
CCL6793E The terminal is in the wrong state
for the requested action.
Explanation: An action was requested when the
terminal was in the wrong state, for example:
disconnect while the terminal was not idle.
System Action: Wait and try again after a fixed
period of time.
User Response: Wait and try again after a
period of time.
CCL6794E Cursor could not be set to row {0},
column {1} - out of range.
Explanation: Either the row {0} or the column
(1} are off the screen.
System Action: System action is not required.
User Response: Check if either the row or the
column are out of range.
CCL6795E Unsupported datastream received
from CICS - command is {0}.
Explanation: The datastream received from
CICS could not be parsed.
System Action: System action is not required.
User Response: For information only.
CCL6796E Transaction {0} failed, return code
{1}.
Explanation: Transaction {0} failed to start, did
not complete, or timed out.
System Action: None.
User Response: Check the Read Timeout value
for the terminal if the transaction timed out.
Check the Client and CICS server logs for more
information on why the transaction failed.
CCL6797E Failed to delete terminal.
Explanation: Terminal could not be deleted.
System Action: Wait, then try again.
User Response: Check if terminal is still in use.
62 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6798E Unknown attribute type {0}.
Explanation: The attribute type {0} is not
supported.
System Action: System action is not required.
User Response: Check attribute type.
CCL6799I Return code {1} from {0} call.
Explanation: The EPI call {0} returned the
return code {1}.
System Action: System action is not required.
User Response: Check return code; if it is not 0
than check for error.
CCL6800I ECI parameters on entry.
Call_Type = Call Type,
Extend_Mode = Extend Mode,
Luw_Token = Luw Token,
Commarea_Length = Commarea
Length, Cics_Rc = Cics Rc,
Message_Qualifier = Message
Qualifier outbound Commarea
length = outbound data length.
Explanation: These are the parameters passed
to the CTG JNI layer. The ECI call specified will
be called with the parameters set here. Outbound
data length can be specifed using the
setCommareaOutboundLength API call.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6801I CcicsECI: Performed parameter
conversion. parameter name =
name, parameter value = value
Explanation: The CTG has converted the
specified parameter to the correct format and
will use this for the ECI call.
System Action: CTG processing will continue.
User Response: No further action is required.

CCL6802I CcicsECI: Input commarea
information. commarea length =
length, commarea address =
address.
Explanation: The CTG will pass the commarea
described in the message on the ECI call.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6803I CcicsInit: Userid password
authentication enabled.
Explanation: The AUTH_USERID_PASSWORD
environment variable has been set, and Userids
and Passwords will be authenticated against the
appropriate security mechanisms.
System Action: The CTG will start with userid
and password authentication enabled.
User Response: Valid user ids and passwords
should be used when making calls to CICS If
authentication is not required, the
AUTH_USERID_PASSWORD environment
variable should be unset. Note: Setting
AUTH_USERID_PASSWORD=NO still makes the
environment variable set. Use unset
AUTH_USERID_PASSWORD to ensure it is not
set.
CCL6804I CcicsECI: Returned commarea
information. commarea length =
length, commarea address =
address, inbound commarea data
length = inbound data length
Explanation: The CTG returned the commarea
decribed after a call to CICS. Inbound data
length refers to the length after null stripping has
occurred.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6802I CCL6807I
CCL6805I ECI parameters on exit. Call_Type
= Call Type, Extend_Mode = Extend
Mode, Luw_Token = Luw Token,
Commarea_Length = Commarea
Length, Cics_Rc = Cics Rc,
Message_Qualifier = Message
Qualifier
Explanation: The ECI parameters specified were
set as displayed just before exit from the CTG
JNI interface.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6806I CcicsInit: Register with RRS.
Return code = rc
Explanation: This displays the return code from
the RRS registration call (crggrm) which registers
the CTG as a resource manager.
System Action: CTG processing will continue.
User Response: If the return code is non-zero,
the user should contact their support
representative for more information and
diagnosis, or see the z/OS v1r2 MVS
Programming: Resource Recovery book
(sa22-7616), section 5.1 -
Register_Resource_Manager, for details of the
return code and any corrective action which
should be taken.
CCL6807I CcicsInit: Set exitcode with RRS.
Return code = rc
Explanation: This displays the return code from
the RRS set exit information call (crgseif).
System Action: CTG processing will continue.
User Response: If the return code is non-zero,
the user should contact their support
representative for more information and
diagnosis.
Messages 63

CCL6808I CCL6814I
CCL6808I CcicsECI: Authorise
userid/password with RACF.
Return code = rc, errno = error
number, errno2 = reason code.
Explanation: This displays the return code from
the __passwd call used to authenticate the
username and password, and the system error
number. Please refer to the problem
determination section of the z/OS
Administration Guide for further details of
security errors.
System Action: If the return code is non-zero,
the CTG will return an ECI_SECURITY_ERROR,
otherwise it will continue processing.
User Response: If the return code is non-zero,
see the C/C++ Run-Time Library Reference book
(SC28-1663), and refer to the section describing
the __passwd() call. More detail on the reason
code can be found in UNIX System Services
Messages and Codes (SC28-1908-10)
CCL6809I getRACFUID: Map X.509
certificate to RACF userid. Return
code = rc, errno = error number,
errno2 = reason code.
Explanation: This displays the return code from
the authorisation call, and the system error
number.
System Action: CTG processing will continue.
User Response: If the return code is non-zero,
see the C/C++ Run-Time Library Reference book
(SC28-1663), and refer to the section describing
the pthread_security_np() call. More detail on the
reason code can be found in UNIX System
Services Messages and Codes (SC28-1908-10)
CCL6810I connopen: First request on TCB
address = address.
Explanation: The address specified is the
address of the TCB used by this connection. The
first ECI request on the specified TCB has been
received. A pipe has not yet been allocated.
System Action: CTG processing will continue.
User Response: No further action is required.
64 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL6811I connclean: Cleanup routine entry,
TCB address = address.
Explanation: The CTG is performing routine
cleanup. This will close and deallocate the pipe,
and is called on thread cleanup by the system.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6812I CcicsECI: EXCI version 2 not
supported on server = server
Explanation: The server specified does not
support the use of EXCI version 2.
System Action: The CTG will retry the request
using an EXCI version 1 parameter block.
User Response: Support for EXCI v2 on CICS
Transaction Server for OS/390 v1.3 is provided
by APAR PQ38644.
CCL6813I CcicsInit: Running under
Websphere z/OS.
Explanation: The CTG is running under
Websphere z/OS platform v4 or later.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6814I CcicsECI: Global transaction
mode detected.
Explanation: The CTG has detected a Global
Transaction running on this thread This will only
occur if running under WebSphere Application
Server for z/OS v4 or later, and when using the
J2EE ECI connector.
System Action: The ECI request will join the
Global Transaction. The CTG will not set the
EXCI SYNCONRETURN option.
User Response: No further action is required.

CCL6815E CcicsECI: Retrieve Side
Information Fast failed. RRM
Return code = rc.
Explanation: The call to Retrieve Side
Information Fast (atrrusf) failed with the
specified return code.
System Action: The CTG will return a system
error on the associated ECI request.
User Response: If the return code is non-zero,
the user should contact their support
representative for more information and
diagnosis, or see the z/OS v1r2 MVS
Programming: Resource Recovery book
(sa22-7616), section 7.25 -
Retrieve_Side_Information_Fast, for details of the
return code and any corrective action which
should be taken.
CCL6816E CcicsECI: Retrieve Current
Context Token failed. RRM
Return code = rc.
Explanation: The call to Retrieve Current
Context Token (ctxrcc) failed with the specified
return code.
System Action: The CTG will return a system
error on the associated ECI request.
User Response: If the return code is non-zero,
the user should contact their support
representative for more information and
diagnosis, or refer to the z/OS v1r2 MVS
Programming: Resource Recovery book
(sa22-7616-01), section 6.7 -
Retrieve_Current_Context_Token, for details of
the return code and any corrective action which
should be taken.
CCL6817E CcicsECI: Switch Context failed.
RRM Return code = rc.
Explanation: The call to Switch Context
(ctxswch) failed with the specified return code.
System Action: The CTG will return a system
error on the associated ECI request.
User Response: If the return code is non-zero,
the user should contact their support
CCL6815E CCL6820E
representative for more information and
diagnosis, or refer to the z/OS v1r2 MVS
Programming: Resource Recovery book
(sa22-7616-01), section 6.10 - Switch_Context, for
details of the return code and any corrective
action which should be taken.
CCL6818E CcicsECI: Begin Context failed.
RRM Return code = rc.
Explanation: The call to Begin Context (ctxbegc)
failed with the specified return code.
System Action: The CTG will return a system
error on the associated ECI request.
User Response: If the return code is non-zero,
the user should contact their support
representative for more information and
diagnosis, or refer to the z/OS v1r2 MVS
Programming: Resource Recovery book
(sa22-7616-01), section 6.1 - Begin_Context, for
details of the return code and any corrective
action which should be taken.
CCL6819I CcicsECI: End Context failed.
RRM Return code = rc.
Explanation: The call to End Context (ctxendc)
failed with the specified return code.
System Action: The CTG will return a system
error on the associated ECI request.
User Response: If the return code is non-zero,
the user should contact their support
representative for more information and
diagnosis, or refer to the z/OS v1r2 MVS
Programming: Resource Recovery book
(sa22-7616-01), section 6.3 - End_Context, for
details of the return code and any corrective
action which should be taken.
CCL6820E CcicsECI: Error in
GetStringPlatform function.
Return code = rc, dataarea=data
area, length = length.
Explanation: The call to GetStringPlatform has
failed with the specified return code and
information.
Messages 65

CCL6821E CCL6827E
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6821E CcicsECI: Error in
GetStringPlatformLength
function. Return code = rc.
Explanation: The call to
GetStringPlatformlength has failed with the
specified return code and information.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6822E CcicsECI: EXCI function error.
Function Call = function call,
Response = response code, Reason =
reason code, Subreason field-1 =
subreason field 1, subreason field-2
= subreason field 2, Cics_Rc = rc.
Explanation: The EXCI call failed with the error
codes displayed.
System Action: The CTG will return an
appropriate error to the application and will
continue processing.
User Response: The user should refer to the
CICS External Interfaces Guide (sc33-1944), to
determine the cause. The EXCI function being
performed is specified by the Function Call data
in the message, which maps to the EXCI calls as
follows; 1=Initialize_User, 2=Allocate_Pipe,
3=Open_Pipe, 4=Close_Pipe, 5=Deallocate_Pipe,
6=DPL_Request.
CCL6823E CcicsECI: EXCI DPL_REQUEST
specific error. RESP value =
response code, RESP2 value =
response code 2, Abend Code =
abend code, Cics_Rc = rc.
Explanation: A request failed with a DPL
specific error. The error codes returned by the
DPL_REQUEST are displayed.
System Action: The CTG will return an
appropriate error to the application and will
continue processing.
66 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: The user should refer to the
CICS External Interfaces Guide (sc33-1944), to
determine the cause of the error.
CCL6825E CcicsECI: Unsupported call type.
Call_Type = call type, Cics_Rc =
cics rc.
Explanation: This message is issued when an
invalid EXCI call is being attempted. The only
valid call types for use with EXCI are
ECI_SYNC, ECI_STATE_SYNC and
ECI_SYNC_TPN.
System Action: The CTG will return an
appropriate error to the application and will
continue processing.
User Response: The user should only use valid
call types on the z/OS platform.
CCL6826E CcicsECI: Invalid commarea
length. Commarea_Length =
commarea length, Size of Commarea
=commarea size, Cics_Rc = rc.
Explanation: The commarea length defined, or
the actual length of the commarea is too large,
and is therefore invalid. The maximum length
supported is 32659 bytes.
System Action: The CTG will return an
appropriate error to the application and will
continue processing.
User Response: The user should ensure the
maximum length of commarea used does not
exceed 32659 bytes.
CCL6827E CcicsECI: Error message from
CICS: cics_error.
Explanation: An error message has been
returned directly from the CICS region, and is
displayed.
System Action: CTG processing will continue.
User Response: The user should refer to the
CICS Messages and Codes book (gc33-1694-35),
for details of the error.

CCL6828I ECI Entry parameters. Call_Type =
Call Type, Extend_Mode = Extend
Mode, Luw Token = Luw Token,
Commarea_Length = Commarea
Length, Message_Qualifier =
Message Qualifier, Timeout =
Timeout.
Explanation: The ECI request will be executed
with the displayed parameters.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6829I ECI Server Name= server_name,
Program Name = program_name,
Transid = transid.
Explanation: The ECI Request will be executed
using the displayed parameters.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6830I ECI Commarea set in ECI block =
commarea length.
Explanation: commarea length is the length of the
commarea specified on the ECI Request.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6831I CcicsECI: Memory Allocation
Failure Cics_RC set to cics_rc.
Explanation: cics_rc will be set to
ECI_ERR_RESOURCE_SHORTAGE. This
message applies to the Solaris platform only, and
indicates a malloc() failure.
System Action: CTG processing will continue.
User Response: The user should refer to the
Solaris documentation to determine what
corrective action is necessary to provide adequate
memory to the CTG process.
CCL6828I CCL6835I
CCL6832I ECI Return values. Luw_Token =
luw token, Cics_RC = cics rc,
Message_Qualifier = message
qualifier, Abend code = abend code
Explanation: The specified parameters were
returned to the CTG after an ECI request.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6833I EPI Get Sys Error Doesn’t call the
client fixed values are Cics_RC =
cics rc, Cause = cause, Value =
value.
Explanation: The message provides details of
the last system error and is triggered by an API
call.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6834I EPI Event Exit Parameters . Size =
size, Event = event, EndReason =
endreason, Cics_RC = rc.
Explanation: The message details what the
specified data is set to after an EPI_GET_EVENT.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6835I EPI Sense Code Exit Parameters.
SenseCode = sense code, Cics_RC =
rc.
Explanation: The CTG is about to exit from the
EPI Sense Code call with a sense code and return
code as indicated.
System Action: CTG processing will continue.
User Response: No further action is required.
Messages 67

CCL6836I CCL6844I
CCL6836I EPI ATI State Exit Parameters.
ATIState = ati state, Cics_RC = rc.
Explanation: The CTG is about to exit from the
EPI ATI State call with an ATI state and return
code as indicated.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6837I EPI Reply Entry Parameters.
Terminal Index = terminal index,
Size = size.
Explanation: This message shows that the CTG
is about to send an EPI Reply call, using the
specified parameters.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6838I EPI Start Transaction Entry
Parameters. Terminal Index =
terminal index, TransId = transaction
id, Size=size.
Explanation: This messages shows the CTG is
about to start a transaction on the specified
terminal with the specified transaction id.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6839I EPI Delete Terminal Entry
Parameters. Terminal Index =
terminal index.
Explanation: The CTG is about to delete the
terminal with the specified terminal index.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6840I EPI Inquire System Entry
Parameters. Terminal Index =
terminal index.
Explanation: The CTG is about to inquire which
system the terminal specified is connected to.
68 CICS Transaction Gateway: CICS Transaction Gateway Messages
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6841I EPI Add Terminal Entry
Parameters. Server = server,
NetName = netname, DeviceType =
device type.
Explanation: The CTG is about to install or
reserve a terminal resouce to the specified server,
with the specified netname, and of the specified
device type.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6842I EPI Server List Entry Parameters.
Number of Systems = number of
systems.
Explanation: The CTG is about to list the CICS
Systems available to be used by the EPI API.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6843I EPI Initialise/Terminate Entry
Parameters. Call_Type = call type.
Explanation: The CTG is about to initialize or
terminate the EPI interface. A call type of 1
indicates initialization, all other values indicate
termination.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6844I ESI verifyPassword Exit results
Server = server, Cics_RC = return
code.
Explanation: The specified return code was
received from the specified server following an
ESI verifyPassword request.
System Action: CTG processing will continue.
User Response: If the return code is non-zero,
the user can reference the cics_esi.h file supplied
with the CTG for information on the return code.

CCL6845I EPI Purge Terminal Entry
Parameters. Terminal Index =
terminal index.
Explanation: The CTG is about to purge the
terminal specified by the terminal index.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6846I EPI Purge Terminal Exit
Parameters. Cics_RC = rc.
Explanation: The CTG has completed the purge
terminal request, and is exiting the function with
the specified return code.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6847I EPI Add Extended Terminal Entry
Parameters. Server = server,
NetName = netname, DeviceType =
device type, add type = add type,
Install Timeout = install timeout,
Read Timeout = read timeout,
CCSid = ccs id, Signon Type =
signon type.
Explanation: The CTG is about to install or
reserve an extended mode terminal resouce to
the specified server, with the specified netname,
and of the specified device type. Other
parameters specified are as displayed.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6848I EPI Add Extended Terminal Exit
Parameters. Server = server,
NetName = netname, Termid=
termid, Termindex = terminal index,
signon Type = signon type, max
data = max data, Cics_RC = return
code.
Explanation: The attempt to install or reserve
an extended mode terminal resouce to the
specified server has completed with the return
CCL6845I CCL6852I
code specified. Other parameters retured are as
specified.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6849I EPI Set Security Entry Parameters.
Terminal Index = terminal index.
Explanation: The CTG will set security on the
terminal resource specified by the terminal index.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6850I EPI Delete Terminal Exit
Parameters. Cics_RC = return code.
Explanation: The CTG completed the Delete
Terminal request with the specified return code.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6851I EPI Set Security Exit Parameters.
Cics_RC = return code.
Explanation: The CTG completed the Set
Security call with the specified return code.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6852I EPI Add Terminal Exit
Parameters. Server = server,
NetName = netname, Termid=
termid, Termindex = terminal index,
signon Type = signon type, max
data = max data, Cics_RC = return
code.
Explanation: The CTG completed the EPI Add
Terminal request with the specified return code.
Other parameters returned are as specified.
System Action: CTG processing will continue.
User Response: No further action is required.
Messages 69

CCL6853I CCL6861I
CCL6853I ESI verifyPassword Entry
Parameters Server = server.
Explanation: The CTG is about to perform a
verifyPassword request to the server specified.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6854I ESI changePassword Entry
Parameters Server = server.
Explanation: The CTG is about to perform a
changePassword request to the server specified.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6855I ESI changePassword Exit results
Server = server, Cics_RC = return
code.
Explanation: The CTG completed the change
password request to the specified server with the
displayed return code.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6856I EPI ATI State Entry Parameters.
Terminal Index = terminal index,
ATIState = ATI state.
Explanation: The CTG is about to alter or query
the ATI state on the server specified. If ATI state
is specified, the ATI state will be changed.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6857I EPI Event Entry Parameters.
Terminal Index = terminal index,
Wait State = wait state.
Explanation: The CTG is about to process a
GET_EVENT on the terminal specified, with a
wait state as shown.
System Action: CTG processing will continue.
70 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: No further action is required.
CCL6858I EPI Event Add Terminal Exit
Parameters. Server = server,
NetName = netname, Termid=
terminal id, Termindex = terminal
index, signon Type = signon type,
max data = max data, Cics_RC =
return code.
Explanation: The CTG has completed the Add
Terminal request with the specified return code.
Other parameters returned are as specified.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6859I EPI Initialise/Terminate Exit
Parameters. Cics_RC = return code.
Explanation: The CTG has completed
initialising or terminating the EPI interface. The
return code from this operation is as specified.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6860I EPI Inquire System Exit
Parameters. System = system,
Cics_RC = return code.
Explanation: The CTG has completed the
Inquire System call. The system returned is the
one connected to the terminal resource specified
on the call. The return code for the call is as
specified.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6861I EPI Reply Exit Parameters.
Cics_RC = return code.
Explanation: The CTG has completed the EPI
Reply requested with the specified return code.
System Action: CTG processing will continue.
User Response: No further action is required.

CCL6862I EPI Sense Code Entry Parameters.
Terminal Index = teminal index.
Explanation: The CTG is about to perform an
EPI Sense Code call for the terminal resource
specified by the terminal index.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6863I EPI Start Transaction Exit
Parameters. Cics_RC = return code.
Explanation: The CTG has completed the EPI
Start Transaction call with the specified return
code.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6864I EPI Server List Exit Parameters.
Cics_RC = return code.
Explanation: The CTG has completed the EPI
Server List call with the specified return code.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6865I ECI Server List Entry Parameters.
Number of Systems = number of
systems.
Explanation: The CTG is about to request a list
of the servers that are available for ECI
connections. The maximum number of systems
to be returned is displayed.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6866I ECI Server List Exit Parameters.
Cics_RC = return code.
Explanation: The CTG has completed the ECI
Server List call with the specified return code.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6862I CCL6873E
CCL6867I CICS CP Request Entry
Parameters. length in = length.
Explanation: The CTG is about to obtain the
codepage details from the system This message
should not be displayed when using the MVS
platform.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6868I CICS CP Request Exit Parameters.
data = data, length out = length out,
Rc = return code.
Explanation: The CTG has completed the CP
request call with the specified return code. This
message should not be displayed when using the
MVS platform.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6869E Change trace file name failed.
filename = file name.
Explanation: An attempt to change the JNI
Trace file name to file name has failed.
System Action: CTG will throw an
TFileException. CTG processing will continue.
JNI Tracing continues using the existing file
name.
User Response: User code should handle the
exception. Check that the file name is valid and
can be written to.
CCL6873E conninit: Already initialized.
Explanation: EXCI connection reuse has already
been initialized.
System Action: The CTG will return an
ECI_ERR_SYSTEM_ERROR error.
User Response: The user should contact their
support representative for more information and
diagnosis.
Messages 71

CCL6874E CCL6901E
CCL6874E conninit: Memory allocation
failure for TCB table for number
TCB entries.
Explanation: The CTG was unable to allocate
memory for the number of TCB entries specified.
System Action: The CTG will return an
ECI_ERR_RESOURCE_SHORTAGE error.
User Response: The user should ensure the
CTG has enough memory available to it to
operate correctly.
CCL6875I CcicsECI: EXCI warning. EXCI
Reason = %lu, Subreason field-1
= %lu, subreason field-2 =
199105866″
Explanation: A warning has occurred in EXCI -
See the CICS External Interfaces Guide for
explanation.
System Action: The Server has issued an EXCI
warning; refer to the EXCI documentation for
details.
User Response: Diagnose the warning by
refering to the CICS External Interfaces Guide
and try again.
CCL6876E CcicsECI: EXCI error. EXCI
Reason = return code, Subreason
field-1 = return code, subreason
field-2 = return code
Explanation: An error has occurred in EXCI -
See the CICS External Interfaces Guide for
explanation.
System Action: The Server has issued an EXCI
error; refer to the EXCI documentation for
details.
User Response: Diagnose the error by refering
to the CICS External Interfaces Guide and try
again.
CCL6877E Internal: Unknown Tracepoint!
num = number.
Explanation: JNI Tracing has sent an unknown
trace point to the formatter.
72 CICS Transaction Gateway: CICS Transaction Gateway Messages
System Action: Cannot be sure what will
happen as we do not know this trace point.
User Response: Route this trace to service to
identify the undefined trace point.
CCL6878E Surrogate check failed.
SURROGCHK=yes set in
DFHXCOPT. EXCI Reason =
return code, Subreason field-1 =
return code, subreason field-2 =
return code
Explanation: The surrogate user check has
failed.
System Action: The DPL call is rejected. The
MVS External Security Manager’s return code
and reason code are subreason codes 1 and 2.
User Response: Check whether SURROGCHK
has been set to YES in DFHXCOPT, and that the
credentials are accurate.
CCL6879I Generic pipe used.
Explanation: A generic pipe has been used for
the connection.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6880I Specific pipe used.
NETNAME=name
Explanation: A specific pipe, named name has
been used.
System Action: CTG processing will continue.
User Response: No further action is required.
CCL6901E Exception occurred [{0}]
Explanation: This message is added to the
servlet log when an unexpected error occurs.
System Action: System action is not required.
User Response: Reset TerminalServlet and
restart application.

CCL6902I Initialization: loading property
file {0}
Explanation: This message is added to the
servlet log when the servlet loads a properties
file.
System Action: Servlet opens properties file.
User Response: For information only.
CCL6903E Initialization failed. Property file
{0} not found
Explanation: This message is added to the
servlet log if the servlet cannot find the property
file {0}.
System Action: The servlet will not start.
User Response: Check if property file exists and
the location is correct.
CCL6904E Initialization failed. Error reading
property file {0}
Explanation: The servlet could not read the
property file {0}.
System Action: The servlet will not start.
User Response: Ensure that the servlet property
file is in the correct format.
CCL6905W Initialization: property {0}={1} is
invalid and has been ignored.
Explanation: This message is added to the
servlet log if, during initialization, the servlet
finds that an initialization parameter or property
file entry is not valid. This could mean either
that the property name is incorrect, or that the
value specified is not a valid setting for the
property.
System Action: The servlet continues running.
User Response: Check if property is valid.
CCL6902I CCL6911W
CCL6906I Initialization completed
successfully.
Explanation: This message is added to the
servlet log when the servlet has started.
System Action: Servlet ready to start.
User Response: For information only.
CCL6907I The servlet is shutting down. In
progress sessions will be
terminated.
Explanation: This message is added to the
servlet log when the servlet begins shutting
down.
System Action: The servlet will shut down.
User Response: For information only.
CCL6908I The servlet has now stopped.
Explanation: This message is added to the
servlet log when the servlet has been unloaded.
System Action: Unloading servlet.
User Response: For information only.
CCL6910W The requested action: {0} is
unrecognized.
Explanation: This message is added to the
servlet log if the value of the ″request″ parameter
is unrecognized. The only supported values of
″request″ are ″send″ and ″disconnect″.
System Action: The request is not completed.
User Response: Check that request is send or
disconnect.
CCL6911W Failed to allocate a terminal for
this request.
Explanation: A terminal could not be allocated
for a user. This could be because a terminal
could not be connected to CICS (for example, if
the server is down), or the maximum number of
terminals are in use.
System Action: Unable to allocate a terminal.
Messages 73

CCL6913W CCL6923I
User Response: Check server is running and
maximum number of terminals has not been
exceeded.
CCL6913W File {0} not found
Explanation: The file indicated could not be
loaded by the servlet.
System Action: System unable to load file.
User Response: Check if file is available and is
in the correct location.
CCL6914I Setting property {0} to the value:
{1}
Explanation: If extended logging is on, this
message is added to the servlet log when the
servlet is requested to set a property value.
System Action: Set property value.
User Response: For information only.
CCL6915I Initialization: reading parameters
Explanation: This message is added to the
servlet log when the servlet begins processing its
initialization parameters.
System Action: Initialization reading
parameters.
User Response: For information only.
CCL6916E Failed to initialize terminal pool.
The error message is: {0}
Explanation: This message is added to the
servlet log if an error occurs while creating the
terminal pool. The servlet will not start.
System Action: Servlet exit.
User Response: Check error message.
CCL6917I Creating screen handler bean {0}
Explanation: If extended logging is on, this
message is added to the servlet log when the
servlet has loaded a screen handler bean.
74 CICS Transaction Gateway: CICS Transaction Gateway Messages
System Action: Servlet loading screen handler
bean.
User Response: For information only.
CCL6918I Getting the property named {0}
Explanation: If extended logging is on, this
message is added to the servlet log when the
servlet is requested to display a property value.
System Action: Servlet displays a property
value.
User Response: For information only.
CCL6919W The property named {0} does not
exist
Explanation: This message is added to the
servlet log when the servlet is requested to set or
to display a property which it does not
recognize.
System Action: Servlet cannot find property.
User Response: Check property name is correct
and exists.
CCL6920I Setting screen wrapper class to {0}
Explanation: Screen wrapper is being set to a
different class.
System Action: System action is not required.
User Response: For information only.
CCL6921I Handling a request
Explanation: If extended logging is on, this
message is added to the servlet log when a
request is processed.
System Action: Execute request.
User Response: For information only.
CCL6923I Redirecting to page: {0}
Explanation: If extended logging is on, this
message is added to the servlet log when the
next page to display to the user has been
determined.

System Action: Redirect to a loaded page.
User Response: For information only.
CCL6924E An error occurred while
processing the request.
Explanation: An error occurred while a request
was being processed. Further messages should
indicate the cause of the problem.
System Action: Terminate request.
User Response: Check further messages for
cause of problem.
CCL6925I Request processing has
completed.
Explanation: If extended logging is on, this
message is added to the servlet log when a
request has been processed.
System Action: Request has been completed.
User Response: For information only.
CCL6999E Unable to open ini file {0}
Explanation: The Gateway cannot find CTG.INI,
or the ini file specified by the user.
System Action: The Gateway stops; it will not
run without an ini file.
User Response: Check that CTG.INI exists in
the bin directory, or that the ini file specified
through the CICSCLI environment variable
exists. Run the configuration tool if necessary to
create an ini file.
CCL7023E Command option option is invalid
Explanation: An invalid command option was
specified when starting the CICSTERM or
CICSPRNT 3270 emulator.
System Action: The emulator terminates.
User Response: Restart the emulator with the
correct option.
CCL6924E CCL7028E
CCL7024E Command option option must
specify a value
Explanation: A CICSTERM or CICSPRNT
command was issued with no value supplied for
the named required option.
System Action: The emulator terminates.
User Response: Restart the emulator using a
valid value for the option.
CCL7025E Command option option cannot be
used more than once
Explanation: On a CICSTERM or CICSPRNT
command, the named option was used more
than once. This is invalid.
System Action: The emulator terminates.
User Response: Restart the emulator using the
correct options.
CCL7026E Command option option1 cannot
be used with option option2
Explanation: The two named options, used on a
CICSTERM or CICSPRNT command, were
incompatible.
System Action: The emulator terminates.
User Response: Restart the emulator using the
correct options.
CCL7027E Command option option1 or
option2 must be provided
Explanation: A CICSPRNT command did not
include one of the named required options.
System Action: The emulator terminates.
User Response: Restart the emulator using the
correct options.
CCL7028E Cannot open binding file file name
Explanation: CICSTERM could not find or open
the specified color, or keyboard, binding file.
System Action: The emulator terminates.
Messages 75

CCL7029E CCL7036E
User Response: Ensure the required binding
files exist and are correctly specified, then restart
the emulator.
CCL7029E Out of memory processing
binding file file name
Explanation: CICSTERM ran out of memory
while processing a color, or keyboard, binding
file.
System Action: The emulator terminates.
User Response: Reduce the number of bindings
specified in the file or try to provide more
system free memory; then restart the emulator.
CCL7030E Error detected at line number in
binding file file name - duplicate
bind for item item
Explanation: CICSTERM detected an error in a
color, or keyboard, binding file. Only one
binding is allowed for the specified item.
System Action: The emulator terminates.
User Response: Correct the binding file and
restart the emulator.
CCL7031E Error detected at line number in
binding file file name - unknown
command command
Explanation: CICSTERM detected an error in a
color, or keyboard, binding file. The specified
command was not a valid binding command.
System Action: The emulator terminates.
User Response: Correct the binding file and
restart the emulator.
CCL7032E Error detected at line number in
binding file file name - invalid
function function
Explanation: CICSTERM detected an error in a
keyboard binding file. The specified item was not
a valid 3270 keyboard function.
System Action: The emulator terminates.
76 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: Correct the binding file and
restart the emulator.
CCL7033E Error detected at line number in
binding file file name - invalid
modifier modifier
Explanation: CICSTERM detected an error in a
keyboard binding file. The specified item was not
a valid workstation keyboard modifier value.
System Action: The emulator terminates.
User Response: Correct the binding file and
restart the emulator.
CCL7034E Error detected at line number in
binding file file name - invalid key
key
Explanation: CICSTERM detected an error in a
keyboard binding file. The specified item was not
a valid workstation key name.
System Action: The emulator terminates.
User Response: Correct the binding file and
restart the emulator.
CCL7035E Error detected at line number in
binding file file name - invalid
attribute attribute
Explanation: CICSTERM detected an error in a
color binding file. The specified item was not a
valid 3270 screen field attribute.
System Action: The emulator terminates.
User Response: Correct the binding file and
restart the emulator.
CCL7036E Error detected at line number in
binding file file name - invalid
color color
Explanation: CICSTERM detected an error in a
color binding file. The specified item was not a
valid workstation display color.
System Action: The emulator terminates.

User Response: Correct the binding file and
restart the emulator.
CCL7037E Unable to communicate with the
CICS Client
Explanation: CICSTERM or CICSPRNT could
not communicate with the client process. This
probably means the client was unable to start.
System Action: The emulator terminates.
User Response: Try to start the client using the
CICSCLI /S command.
CCL7038E The CICS Client has not been
started
Explanation: CICSTERM or CICSPRNT did not
start because the client was not, or could not be,
started.
System Action: The emulator terminates.
User Response: Try to start the client using the
CICSCLI /S command.
CCL7039I EMULATOR - CICS server
selection
Explanation: The emulator was started with the
/R or /S option and a server name was not
specified to connect CICSTERM or CICSPRNT to.
System Action: A list of available server names
is provided.
User Response: Choose the required server
from the list or CANCEL to terminate the
emulator.
CCL7043E Terminal screen width is invalid -
reset to 80 columns
Explanation: The server returned a terminal
definition that contained an invalid screen width
for the terminal emulator. (Screen widths are
normally 40, 80, or 132 columns.)
System Action: The emulator resets the screen
width to a standard 80 columns. Output may
appear corrupted because the client and server
terminal definitions may not match.
CCL7037E CCL7046E
User Response: Check with the server system
administrator to determine why the terminal
definition is incorrect.
CCL7044E Terminal screen size is too large -
reset to maximum
Explanation: The server returned a terminal
definition that contained a screen size too large
for the terminal emulator. The product of screen
width and screen depth cannot exceed 4096.
System Action: The emulator resets the screen
depth to the maximum number of rows. Output
may appear corrupted because the client and
server terminal definitions may not match.
User Response: Check with the server system
administrator to determine why the terminal
definition is incorrect.
CCL7045E Connection lost with server server
Explanation: The connection with the specified
server has been lost. This would normally
indicate that the server is no longer available.
System Action: The emulator waits until the
server is available again and tries to reconnect.
User Response: Wait for the connection to be
reestablished or clear the error message and
terminate the emulator.
CCL7046E The CICS Client reported a
resource shortage
Explanation: The client returned a resource
shortage error. This would normally indicate that
the client ran out of free memory. If SNA
communications are being used, it may indicate
that there are insufficient LU6.2 sessions
available.
System Action: The emulator attempts to
continue, although further requests to the client
may receive the same error response.
User Response: If the client is very busy the
resource shortage may disappear when the client
becomes less loaded. Otherwise, examine the
client error log and, if possible, trace information
to determine the cause of the error. Then, stop
Messages 77

CCL7047E CCL7054I
the client and reconfigure it to provide more of
the particular resource causing the problem.
CCL7047E The CICS Client is closing down
Explanation: CICSTERM or CICSPRNT could
not be started because the client was closing
down.
System Action: The emulator terminates.
User Response: Wait for the client to close
down, then restart the emulator.
CCL7048E Server server is undefined
Explanation: The client indicated that the
specified server name is unknown.
System Action: The emulator terminates.
User Response: Ensure the required server
name is one of those listed in the client
initialization file, or use the /S option to select
from a list of valid names.
CCL7049E Unable to connect to server server
Explanation: The client was unable to connect
to the specified server.
System Action: The emulator terminates.
User Response: Check for other messages and
examine the client error log to determine the
cause of the error.
CCL7050E The MaxBufferSize setting is too
small for this terminal
Explanation: The emulator tried to send more
data than the client could accept.
System Action: The data is ignored and the
emulator continues.
User Response: Increase the MaxBufferSize
value in the Client section of the client
initialization file and stop, then restart, the client.
78 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL7051E Server server does not support
client terminals
Explanation: Client 3270 emulator terminals are
not supported by all CICS servers. The specified
server is one of those that does not provide this
support. If this is a CICS/400 server this message
can also be generated if CICS is unavailable.
System Action: The emulator terminates.
User Response: Select a server that does
support client terminals or check with the server
system administrator to determine why client
terminals are not supported.
CCL7052E Server server rejected this terminal
with a security error
Explanation: The specified server is secure and
required a valid userid and password before it
could install a client terminal.
System Action: The emulator terminates.
User Response: Enter a valid userid and
password when prompted by the client.
Alternatively, to avoid the prompt use the
CICSCLI /C command to set the userid and
password.
CCL7053E Errors found while
communicating with server server
Explanation: The client encountered errors
while communicating with the specified server.
System Action: The emulator ignores the errors
and tries to continue.
User Response: Check for other messages and
examine the client error log to determine the
cause of the error.
CCL7054I Server server is currently
unavailable
Explanation: The client found that the specified
server was currently unavailable.
System Action: The emulator waits until the
server becomes available and then tries to
connect.

User Response: Wait for the connection to be
established or clear the error message and
terminate the emulator.
CCL7055E Terminal install failed - NetName
name is invalid
Explanation: The server rejected the terminal
because the specified NetName was invalid.
System Action: The emulator terminates.
User Response: Ensure the requested terminal
NetName is correct and defined at the server. If
the error persists, check with the server system
administrator for the cause of the error.
CCL7056E Terminal install failed - Model
model is invalid
Explanation: The server rejected the terminal
because the specified Model was invalid.
System Action: The emulator terminates.
User Response: Ensure the requested terminal
Model is correct and defined at the server. If the
error persists, check with the server system
administrator for the cause of the error.
CCL7057E Terminal install failed - NetName
name is already installed
Explanation: The server rejected the request
because another terminal was already installed
with the same NetName.
System Action: The emulator terminates.
User Response: Ensure the requested terminal
NetName is correct. If the error persists, check
with the server system administrator for the
cause of the error.
CCL7058E Terminal install failed - rejected
by the server
Explanation: The server was unable to accept
the terminal and rejected the installation request.
System Action: The emulator terminates.
User Response: Check with the server system
CCL7055E CCL7062E
administrator to determine why the terminal was
rejected.
CCL7059E Terminal install failed - reason
unknown
Explanation: The server rejected the terminal.
System Action: The emulator terminates.
User Response: Check with the server system
administrator to determine why the terminal was
rejected.
CCL7060I DBCS datastream errors detected
Explanation: The terminal emulator detected
errors in the DBCS datastream.
System Action: The terminal emulator ignores
the errors and tries to continue.
User Response: Check with the server system
administrator to determine why incorrect data is
being generated. Client trace information may be
helpful when trying to find these errors.
CCL7061E Unable to open or create print
output file
Explanation: The terminal emulator was unable
to open or create the local print file specified by
the PrintFile option in the client initialization file.
System Action: The print request is ignored and
the terminal emulator continues.
User Response: Ensure the name of the print
file you specified in the client initialization file is
correct and accessible.
CCL7062E Unable to write to the print
output file
Explanation: The terminal was unable to write
to the local print file specified by the PrintFile
option in the client initialization file.
System Action: The print request is ignored and
the emulator continues.
User Response: Ensure the name of the print
Messages 79

CCL7063E CCL7074E
file you specified in the client initialization file is
correct and accessible.
CCL7063E Unable to execute print command
Explanation: The terminal emulator is unable to
execute the local print command specified by the
PrintCommand option in the client initialization
file.
System Action: The print request is ignored and
the emulator continues.
User Response: Ensure the print command you
specified in the client initialization file is correct.
CCL7069E Server server has reported a
transaction ABEND
Explanation: The specified server reported an
ABEND while trying to run the current
transaction. This may have been caused by a
communications failure between the client and
server.
System Action: The terminal emulator ignores
the errors and tries to continue.
User Response: Examine any other messages
and the client error log and server error log to
determine the cause of the error.
CCL7070E Terminal screen depth is invalid -
reset to 24 rows
Explanation: The server returned a terminal
definition that contained an invalid screen depth
for the terminal emulator. (Screen depths are
normally between 10 and 60 rows).
System Action: The terminal emulator has reset
the screen depth to a standard 24 rows. Output
may appear corrupted because the terminal
emulator and server terminal definitions may not
match.
User Response: Check with the server system
administrator to determine why the terminal
definition is incorrect.
80 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL7071E Screen data exceeds the display
space available
Explanation: The server returned more data
than the terminal emulator can accept.
System Action: The excess data is ignored and
the terminal emulator tries to continue.
User Response: Check with the server system
administrator to determine why such a large
amount of data is being generated. Client trace
information may be helpful when trying to find
these errors.
CCL7072E The CICS Client has reached its
MaxServers limit of number
Explanation: The client can only communicate
simultaneously with the number of servers
specified by the MaxServers option in the Client
section of the client initialization file. This limit
has been reached.
System Action: The emulator terminates.
User Response: Use the CICSCLI /X command
to close connections to servers that are no longer
required, or increase the ″MaxServers″ setting in
the client initialization file; then stop and restart
the client.
CCL7073E Terminal install failed - requested
terminal is not a 3270 device
Explanation: The server rejected the terminal
because the server terminal definition does not
represent a 3270 device.
System Action: The emulator terminates.
User Response: Ensure the requested terminal
Model or NetName is correct and correctly
defined at the server. If the error persists, check
with the server system administrator for the
cause of the error.
CCL7074E Terminal install failed - server is
busy
Explanation: The server rejected the terminal
emulator because the server was too busy.

System Action: The emulator terminates.
User Response: Retry the request sometime
later when the server is not so busy.
CCL7098E An internal processing error has
occurred
Explanation: The terminal emulator detected an
unexpected internal error.
System Action: Error information is written to
the client error log.
User Response: Obtain the client error log -
and, if possible, trace information - and refer the
problem to your support organization.
CCL7099I Refer to the error log for more
details
Explanation: An error has occurred for which
further useful diagnostic information has been
written to the client error log.
System Action: Client processing continues.
User Response: Examine the client error log to
obtain the information.
CCL7101 Internal transport error (function,
error)
Explanation: An internal emulator function
failed.
System Action: The message is written to the
error log and the emulator terminates. The
function name and error code are logged.
User Response: If the problem persists, contact
your service organization.
CCL7103 Internal Windows function error
(function)
Explanation: An internal Windows function
failed.
System Action: The message is written to the
error log and the emulator terminates. The
function name is logged.
User Response: If the problem persists, contact
your service organization.
CCL7098E CCL7108E
CCL7104 Emulator has insufficient memory
to create an internal control
structure
Explanation: The emulator is unable to allocate
enough memory to create an internal control
structure.
System Action: The message is written to the
error log and the emulator terminates.
User Response: Try altering the system
configuration to provide more free memory
when the emulator is started, then restart the
emulator.
CCL7105 Emulator received incorrect sized
data block(s) (size1, size2)
Explanation: The emulator has received
incorrect data from the Client daemon.
System Action: The message is written to the
error log and the emulator continues.
User Response: If the problem persists, contact
your service organization.
CCL7106 Emulator ATI table error
Explanation: The emulator has received too
many outstanding ATI requests from the server.
System Action: The message is written to the
error log and the emulator continues.
User Response: Try to establish why the
emulator is receiving large numbers of ATI
requests while being unable to initiate them. If
the problem persists contact your service
organization.
CCL7108E No CICS servers are available
Explanation: There no CICS servers available
for the emulator to use.
System Action: The emulator terminates.
User Response: Check that there are one or
more valid CICS servers in either the CICS Client
Messages 81

CCL7109E CCL7116
initialization file. If load management exits are
active then check that at least one of the servers
the emulator tried to connect to is available.
Examine the Client trace to see which servers the
load management attempted to connect to.
CCL7109E CICS_EpiAddTerminal rejected by
the EPI user exit
Explanation: The EPI user exit (CICSEPIX)
returned CICS_EXIT_DONT_ADD_TERMINAL
and rejected the CICS_EpiAddTerminal request.
System Action: The EPI terminal is not added.
User Response: Check with the server system
administrator to determine why the terminal was
rejected.
CCL7110 CICS_EciInitializeExit returned rc
= rc
Explanation: The ECI user exit function
CICS_EciInitializeExit was called and returned a
return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7111 CICS_EciTerminateExit returned
rc = rc
Explanation: The ECI user exit function
CICS_EciTerminateExit was called and returned a
return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7112 CICS_EciExternalCallExit1
returned rc = rc
Explanation: The ECI user exit function
CICS_EciExternalCallExit1 was called and
returned a return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
82 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: None.
CCL7113 CICS_EciExternalCallExit2
returned rc = rc
Explanation: The ECI user exit function
CICS_EciExternalCallExit2 was called and
returned a return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7114 CICS_EciSystemIdExit returned rc
= rc
Explanation: The ECI user exit function
CICS_EciSystemIdExit was called and returned a
return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7115 CICS_EciDataSendExit returned rc
= rc
Explanation: The ECI user exit function
CICS_EciDataSendExit was called and returned a
return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7116 CICS_EciDataReturnExit returned
rc = rc
Explanation: The ECI user exit function
CICS_EciDataReturnExit was called and returned
a return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.

CCL7117 CICS ECI user exit loaded,
DLLPathName
Explanation: The ECI user exit CICSECIX.DLL
has been successfully loaded, the full path name
being DLLPathName.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7118 About to call CICS_ECIEXITINIT
Explanation: The ECI user exit initialization
function CICS_ECIEXITINIT is about to be
called.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7119 CICS ECI user exit active flag =
flag
Explanation: The ECI user exit initialization has
completed and the boolean ECI exit active flag is
0 for inactive and 1 for active.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7120 About to call ECI user exit
Explanation: An ECI user exit function is about
to be called.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7121 CICS EPI user exit loaded,
DLLPathName
Explanation: The EPI user exit CICSEPIX.DLL
has been successfully loaded, the full path name
being DLLPathName.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7122 About to call CICS_EPIEXITINIT
Explanation: The EPI user exit initialization
function CICS_EPIEXITINIT is about to be called.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7123 CICS EPI user exit active flag =
flag
Explanation: The EPI user exit initialization has
completed and the boolean EPI exit active flag is
0 for inactive and 1 for active.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7124 CICS EPI user exit unloaded,
DLLPathName
Explanation: The EPI user exit CICSEPIX.DLL
has been successfully unloaded, the full path
name being DLLPathName.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7125 CICS_EpiInitializeExit returned rc
= rc
Explanation: The EPI user exit function
CICS_EpiInitializeExit was called and returned a
return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7117 CCL7125
Messages 83

CCL7126 CCL7133
CCL7126 CICS_EpiTerminateExit returned
rc = rc
Explanation: The EPI user exit function
CICS_EpiTerminateExit was called and returned
a return code of rc.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7127 CICS_EpiAddTerminalExit
returned rc = rc, System system,
NetName netname, DevType
devtype
Explanation: The EPI user exit function
CICS_EpiAddTerminalExit was called and
returned a return code of rc. The output values
of System, NetName and DevType are provided.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7128 CICS_EpiTermIdExit returned rc =
rc, TermIndex termindex, System
system
Explanation: The EPI user exit function
CICS_EpiTermIdExit was called and returned a
return code of rc. The values of TermIndex and
System are provided.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7129 CICS_EpiStartTranExit returned rc
= rc, TranId tranid, Data size size:
Explanation: The EPI user exit function
CICS_EpiStartTranExit was called and returned a
return code of rc. The values of TranId and Data
Size are provided, along with a dump of the data
itself.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
84 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL7130 CICS_EpiReplyExit returned rc =
rc, TermIndex termindex, Data size
size:
Explanation: The EPI user exit function
CICS_EpiReplyExit was called and returned a
return code of rc. The values of TermIndex and
Data Size are provided, along with a dump of
the data itself.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7131 CICS_EpiDelTerminalExit
returned rc = rc, TermIndex
termindex
Explanation: The EPI user exit function
CICS_EpiDelTerminalExit was called and
returned a return code of rc. The value of
TermIndex is provided.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7132 CICS_EpiGetEventExit returned rc
= rc, TermIndex termindex,
EventData:
Explanation: The EPI user exit function
CICS_EpiGetEventExit was called and returned a
return code of rc. The value of TermIndex is
provided, along with a dump of the EventData.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7133 CICS_EpiTranFailExit returned rc
= rc, TermIndex termindex,
EventData:
Explanation: The EPI user exit function
CICS_EpiTranFailExit was called and returned a
return code of rc. The value of TermIndex is
provided, along with a dump of the EventData.
System Action: The message is written to the

trace file if tracing is enabled.
User Response: None.
CCL7134 CICS_EpiSystemIdExit returned rc
= rc, System system, NetName
netname, DevType devtype
Explanation: The EPI user exit function
CICS_EpiSystemIdExit was called and returned a
return code of rc. The output values of System,
NetName and DevType are provided.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7135 About to call EPI user exit
Explanation: An EPI user exit function is about
to be called.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL7136E A minimum screen size of number
rows by number columns is
required
Explanation: The screen size available is too
small for cicsterm. The minimum size is 25 rows
by 80 columns.
System Action: The terminal emulator has not
been started.
User Response: Change the screen size of your
terminal before starting cicsterm and retry.
CCL7629 Unable to read Load Manager INI
file filename (reason = error)
Explanation: The client is unable to read the
Load Manager INI configuration file.
System Action: The message is written to the
log and the Load Manager is disabled.
User Response: Make sure that the INI file
being read exists on the disk, and that it is not
read-protected. If the problem persists, contact
your service organisation.
CCL7134 CCL7644
CCL7639 Duplicate parameter parameter
found - ignored
Explanation: This is a warning. A duplicate
parameter heading has been detected in your
Load Manager INI file.
System Action: The client will continue to read
the Load Manager INI file, but will ignore all
duplicate parameters will be ignored.
User Response: If you do not want this
warning to appear in the log, make sure that
there are no duplicate parameters in your Load
Manager INI file.
CCL7640 Duplicate section section found -
ignored
Explanation: This is a warning. A duplicate
section heading has been detected in your Load
Manager INI file.
System Action: The client will continue to read
the Load Manager INI file, but will ignore all
duplicate sections will be ignored.
User Response: If you do not want this
warning to appear in the log, make sure that
there are no duplicate sections in your Load
Manager INI file.
CCL7643 Incomplete or missing section
section - error
Explanation: Your Load Manager INI file is
invalid, and the client could not read the
specified section.
System Action: The Load Manager will be
disabled.
User Response: Make sure that the Load
Manager INI file is valid.
CCL7644 Cannot find parameter parameter -
error
Explanation: A mandatory parameter could not
be found in the Load Manager INI file.
Messages 85

CCL7645 CCL8031E
System Action: The Load Manager will be
disabled.
User Response: Make sure that the Load
Manager INI file is valid.
CCL7645 Paramater parameter has invalid
value value
Explanation: The specified parameter has an
invalid value.
System Action: The Load Manager will be
disabled.
User Response: Make sure that the Load
Manager INI file is valid.
CCL7646 Value for parameter parameter is
too large
Explanation: The value of the specified
parameter is too large.
System Action: The Load Manager will be
disabled.
User Response: Make sure that the value
specified is within the required range.
CCL8024E Unable to communicate with the
CICS Client
Explanation: CICSCLI could not communicate
with the client process. This probably means the
client was unable to start.
System Action: CICSCLI performs no action.
User Response: Try starting the client using the
CICSCLI /S command.
CCL8025I The CICS Client has not been
started
Explanation: No attempt has been made to start
the CICS Client or the CICS Client had not been
started.
System Action: CICSCLI performs no action.
User Response: Start the client using the
CICSCLI /S command.
86 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL8026I Client trace is enabled
Explanation: The CICSCLI /D command was
issued to start client tracing.
System Action: Trace information is appended
to the client trace file specified by the TraceFile
parameter in the client initialization file.
User Response: You can examine the trace file
by using a standard ASCII text editor.
CCL8027I Client trace is disabled
Explanation: The CICSCLI /O command was
issued to stop client tracing.
System Action: No further trace information is
written to the client trace file or to the trace
memory buffer.
User Response: You can examine the trace
and/or dump files by using a standard ASCII
text editor.
CCL8030E Unable to change client trace state
Explanation: The client was unable to set the
requested trace state.
System Action: Service tracing remains
unchanged.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8031E Server server is unknown
Explanation: The specified server name was not
defined in the client initialization file that was
specified when the client first started up.
System Action: CICSCLI performs no action.
User Response: Correct the server name and
reissue the command. If required add the server
to the client initialization file, then stop and
restart the client to activate the changes.

CCL8032E Unable to complete stop request
Explanation: The client was unable to
disconnect from the server.
System Action: CICSCLI performs no action.
User Response: Try using CICSCLI /I; if this
fails examine any other messages and the client
error log to determine the cause of the error.
CCL8033I Connection to server server is
stopping
Explanation: The client accepted the request to
close a connection with a server and is
processing that request.
System Action: It may take some time for the
close request to complete because all active
conversations with the server must complete
first.
User Response: Wait for the connection to close;
if the connection does not close you may have to
force it to close using the CICSCLI /I command.
This forces any open conversations to end.
CCL8034I The CICS Client is stopping
Explanation: The client accepted a request to
close all server connections and to terminate.
System Action: It may take some time for the
close request to complete because all active
conversations with the server must complete
first.
User Response: Wait for the client to stop; if the
client does not stop you may have to force it to
close using the CICSCLI /I command. This forces
any open conversations to end.
CCL8035I The CICS Client is already started
Explanation: A request to start the client was
ignored because it was already started.
System Action: CICSCLI performs no action.
User Response: No further action is required.
CCL8032E CCL8039I
CCL8036E Unable to perform start request,
see Client error log
Explanation: The client was unable to complete
the request to start the connection to a server.
System Action: CICSCLI performs no action.
User Response: Examine any other messages
and the Client error log to determine the cause of
the error.
CCL8037I Connection to server server is
being started
Explanation: The client accepted a request to
start a connection with a server and is processing
that request.
System Action: It may take some time for the
start request to complete because
communications with the server must be
established.
User Response: Wait for the connection to
complete; you can use the CICSCLI /L command
to check connection status.
CCL8038I The CICS Client is starting
Explanation: The client has accepted a request
to start.
System Action: It may take a few moments for
the start request to complete.
User Response: Wait for the client to start; you
can use the CICSCLI /L command to check client
status.
CCL8039I The CICS Client is stopping
Explanation: The client was requested to
perform a function but first had to wait to
terminate following an earlier CICSCLI /X
command.
System Action: The termination processing
continues.
User Response: Wait for the client to terminate.
If the client does not close you may need to force
it close using the CICSCLI /I command. This
forces any open conversations to end.
Messages 87

CCL8040I CCL8051E
CCL8040I No servers are being used by the
CICS Client
Explanation: The client is active but is not
connected to any servers.
System Action: No further action is performed.
User Response: No further action is required.
CCL8042I Server server (using protocol to
netname) is available
Explanation: The client is connected to the
server and the server is available. The client is
connected using the specified protocol to the
system known on the network by the specified
netname.
System Action: Processing continues.
User Response: No further action is required.
CCL8043I Server server (using protocol to
netname) is unavailable
Explanation: The client is connected to the
server but the server is unavailable. The client is
connected using the specified protocol to the
system known on the network by the specified
netname.
System Action: No further action is performed.
User Response: Wait for the server to become
available, or close the connection using the
CICSCLI /X command if the server is no longer
required.
CCL8044I Server server (using protocol to
netname) is connecting
Explanation: The client is waiting to connect to
the server, the state of the server is not yet
known. The client is connecting using the
specified protocol to the system known on the
network by the specified netname.
System Action: The connection processing
continues.
User Response: Wait for the connection to
complete. After completion the status of the
88 CICS Transaction Gateway: CICS Transaction Gateway Messages
server - either available or unavailable - is
known.
CCL8045I Server server (using protocol to
netname) is stopping
Explanation: The connection with the server is
currently waiting to be closed.
System Action: The termination processing
continues.
User Response: Wait for the connection to close.
If the connection does not close you may need to
force it to close using the CICSCLI /I command.
This forces any open conversations to end.
CCL8046E Unable to perform list request
Explanation: The client was unable to perform a
request to list the current server connection
details.
System Action: CICSCLI performs no action.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8050I Requested security information
has been updated
Explanation: The client completed a request to
set the userid and password information for a
secure server.
System Action: Secure server information is
updated.
User Response: No further action is required.
CCL8051E Invalid request to change security
information
Explanation: A CICSCLI command was issued
with the /U or /P options but without the /C
option specifying a server name.
System Action: CICSCLI performs no action.
User Response: Reissue the command with the
correct options.

CCL8052E Unable to make the requested
security information changes
Explanation: The client was unable to perform
the request to change the userid and password
information for a secure server.
System Action: CICSCLI performs no action.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8053E Connection to server server is
already started
Explanation: The client was unable to perform a
request to connect to the named server, because a
connection with the server already exists.
System Action: CICSCLI performs no action.
User Response: If the connection is no longer
required, use the CICSCLI /X command to close
it.
CCL8054E Connection to server server has not
been started
Explanation: The client was unable to perform
the request to start a connection with the
specified server.
System Action: CICSCLI performs no action.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8055E The CICS Client has reached its
MaxServers limit
Explanation: The client can only communicate
simultaneously with the number of servers
specified by the MaxServers option in the Client
section of the client initialization file. This limit
has been reached.
System Action: CICSCLI performs no action.
User Response: Use the CICSCLI /X command
to close connections to servers that are no longer
required. Alternatively, increase the MaxServers
CCL8052E CCL8059I
setting in the client initialization file; then stop
and restart the client.
CCL8056E Size is an incorrect trace size limit
value
Explanation: The CICSCLI /D or CICSCLI /T
command to start client tracing can include an
optional numeric value specifying the maximum
size of data to be traced. The specified size is
either not a numeric value or is outside the
permitted range of 1 - 32767.
System Action: CICSCLI performs no action.
User Response: Reissue the command with the
correct value.
CCL8057I Client error and security pop-ups
have been enabled
Explanation: The CICSCLI /E command was
used to enable presentation of messages in
pop-ups.
System Action: Any client errors and secure
server requests are presented via a pop-up.
User Response: Any pop-ups have to be
acknowledged by the user before further
processing can continue.
CCL8058I Client error and security pop-ups
have been disabled
Explanation: The CICSCLI /N command was
used to disable presentation of messages in
pop-ups. This allows the client to run without
any user interaction.
System Action: Client error messages will be
written to the client error log and secure server
logon requests will fail.
User Response: No further action is required.
CCL8059I Error and security pop-ups were
already enabled
Explanation: The CICSCLI /E command was
used to enable error and security pop-ups but
they were already enabled.
Messages 89

CCL8060I CCL806IE
System Action: Error and security pop-ups
remain enabled.
User Response: No further action is required.
CCL8060I Error and security pop-ups were
already disabled
Explanation: The CICSCLI /N command was
used to disable error and security pop-ups but
they were already disabled.
System Action: Error and security pop-ups
remain disabled.
User Response: No further action is required.
CCL8062I Option option ignored because the
CICS Client is already started
Explanation: The /F option to specify a client
initialization file was included on a CICSCLI
command but this option can be specified only
when the client is first started with the CICSCLI
/S command.
System Action: CICSCLI performs no action.
User Response: If a different client initialization
file is required, the client must be stopped and
restarted.
CCL8063E Option option cannot be used
unless starting the CICS Client
Explanation: The /F option to specify a client
initialization file was included on a CICSCLI
command, but this option can be specified only
when starting the client with the CICSCLI /S
command.
System Action: CICSCLI performs no action.
User Response: If a different client initialization
file is required, the client must be stopped and
restarted.
CCL8065E Unable to change status of client
trace to memory buffer
Explanation: The client was unable to set the
requested trace state.
90 CICS Transaction Gateway: CICS Transaction Gateway Messages
System Action: Service tracing to the memory
buffer remains unchanged.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8066E Unable to start client trace to
memory buffer
Explanation: The client was unable to start the
trace to the memory buffer. This is probably
because sufficient storage could not be allocated.
System Action: Service tracing to the memory
buffer was not started.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8068E Error dumping trace file in
memory buffer to file
Explanation: The client was unable to dump the
trace memory buffer to the dump file. Ensure the
dump file name (in CTG.INI) is valid and the
disk is not full.
System Action: Service tracing to the memory
buffer is not dumped.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8069E Userid userid exceeds the
maximum supported length
Explanation: The length of the userid string
supplied exceeds the maximum supported by the
CICS Client.
System Action: CICSCLI performs no action.
User Response: Reissue the command with a
valid string.
CCL806IE Unable to set error and security
pop-up state
Explanation: The client was unable to set the
security and error pop-up state requested by a

CICSCLI /E or CICSCLI /N command.
System Action: Error and security pop-ups
remain unchanged.
User Response: Examine any other messages
and the client error log to determine the cause of
the error.
CCL8070E Password password exceeds the
maximum supported length
Explanation: The length of the password string
supplied exceeds the maximum supported by the
CICS Client.
System Action: CICSCLI performs no action.
User Response: Reissue the command with a
valid string.
CCL8400I Using ini file {0}
Explanation: You can now specify the ini file to
be used. The Gateway is using either CTG.INI or
the ini file specified by the CICSCLI environment
variable.
System Action: Display the ini file in use, and
write it to the log.
User Response: User response not required.
CCL8401I The Following Ciphers are
Enabled
Explanation: Information following this
message describes the names of the enabled
ciphers.
System Action: System action is not required.
User Response: Information only, no response is
required.
CCL8402I JSSE libraries selected for use.
Explanation: Information detailing security
implementation providing encryption services.
System Action: System action is not required.
User Response: Information only, no response is
required.
CCL8403I SSLIGHT libraries selected for
use.
Explanation: Information detailing security
implementation providing encryption services.
System Action: System action is not required.
User Response: Information only, no response is
required.
CCL8404I JSSE Version unknown
Explanation: Version information for the JSSE
security provider is unavailable.
System Action: System action is not required.
User Response: Information only. no response is
required
CCL8405I {0}
CCL8070E CCL8522E
Explanation: JSSE provider information.
System Action: System action is not required.
User Response: Information only, no response is
required.
CCL8521E Unknown option option
Explanation: An invalid command option was
specified when using the CICSBMSC command.
System Action: CICSBMSC performs no action.
User Response: Reissue the command with the
correct option.
CCL8522E Input file filename must have .bms
or .BMS suffix
Explanation: The CICSBMSC command requires
a BMS source file as input.
System Action: CICSBMSC performs no action.
User Response: Reissue the command with the
correct BMS source file name.
Messages 91

CCL8523E CCL8605
CCL8523E Unable to open BMS input file
filename
Explanation: The CICSBMSC command could
not find, or could not read the supplied BMS
source file.
System Action: CICSBMSC performs no action.
User Response: Check that the BMS source file
name is correct, that the file is available and can
be read.
CCL8524E Unable to open output files
Explanation: The CICSBMSC command is
unable to create output files.
System Action: CICSBMSC processing ends.
User Response: Check that there is sufficient
disk space available for the CICSBMSC output
files.
CCL8526E Error in BMS source file filename
line number
Explanation: The CICSBMSC command has
found an error in an input BMS source file.
System Action: CICSBMSC processing ends.
User Response: Check the BMS macro source at
the line indicated.
CCL8601 Exception exception raised in
class:method [during call request]
Explanation: The exception named, one of the
Ccl:ExCode enumeration values, was raised
during the execution of the class:method method
during the server request indicated by the call
value. An exception object encapsulating details
of the exception is passed to
CclECI:handleException or
CclEPI:handleException and/or thrown via the
C++ exception mechanism.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
92 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL8602 Sending call request to server
Explanation: The client class library is about to
make a server call. The call value indicates the
request type.
System Action: The message is written to the
trace file if tracing is enabled, followed by a
dump of the flow object state.
User Response: None.
CCL8603 Received call reply from server
Explanation: The client class library has
received a reply from the server. The call value
indicates the request type.
System Action: The message is written to the
trace file if tracing is enabled, followed by a
dump of the flow object state.
User Response: None.
CCL8604 EPI call calltype: RC=error,
Event=event
Explanation: The client class library completed
an EPI call. The error value indicates any errors,
the event value indicates the EPI event returned
on GetEvent calls.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL8605 Method class:method invoked:
State=state, ExCode=exception
Explanation: The client class library method
indicated by the class and method values has been
invoked. The state and exception values indicate
the current object state and exception code.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.

CCL8707E Unable to open file filename
Explanation: The CICSCONV utility is unable
to access the file.
System Action: CICSCONV processing ends.
User Response: Check that the file specified is
accessible.
CCL8708I Process file filename
Explanation: The CICSCONV utility is
processing the file.
System Action: CICSCONV processing
continues.
User Response: No further action is required.
CCL8709I Creating file filename
Explanation: The CICSCONV utility is
generating the file.
System Action: CICSCONV processing
continues.
User Response: No further action is required.
CCL8710I Renaming file filename to file
filename
Explanation: The CICSCONV utility is changing
the name of a file that already exists.
System Action: CICSCONV processing
continues.
User Response: No further action is required.
CCL8711I Processing complete
Explanation: The CICSCONV utility has
finished conversion.
System Action: CICSCONV terminates without
error.
User Response: No further action is required.
CCL8707E CCL8807E
CCL8804E The CICS Client/Gateway is not
installed properly
Explanation: The CICS Transaction Gateway or
CICS Univseral Client is not installed correctly.
Registry keys are created at install time.
System Action: The command line application
terminates.
User Response: Reinstall the CICS Transaction
Gateway or CICS Universal Client.
CCL8805E Unable to read from the registry
Explanation: The program tried to read from
the registry but cannot read the appropiate
registry key. This is normally caused by security
settings in the registry.
System Action: The command line application
terminates.
User Response: Get your system administrator
to give read permission to the registry key
HKEY_LOCAL_MACHINE\SOFTWARE\
IBM\CICS Transaction Gateway or
HKEY_LOCAL_MACHINE\SOFTWARE\
IBM\CICS Universal Client.
CCL8806E Unable to write to the registry
Explanation: The program tried to write to the
registry but cannot write the appropiate registry
key. This is normally caused by security settings
in the registry.
System Action: The command line application
terminates.
User Response: Logon as a user who has
permissions to write to either
HKEY_LOCAL_MACHINE\SOFTWARE\
IBM\CICS Transaction Gateway or
HKEY_LOCAL_MACHINE\SOFTWARE\
IBM\CICS Universal Client. Then repeat the
command line option.
CCL8807E Unable to find a JVM
Explanation: When trying to run a Java
application, the application launcher tries to find
a JVM, it does this by querying the registry.
Messages 93

CCL8808E CCL9303
System Action: The command line application
terminates.
User Response: Install a JVM, or use the
CTGJAVA command to point to the Java Virtual
Machine to run.
CCL8808E Unable to find Java runtime
classes
Explanation: When trying to run a Java
application, the Java runtime classes could not be
found.
System Action: The command line application
terminates.
User Response: Install the Java Virtual Machine
(JVM) correctly.
CCL8815E File does not exist
Explanation: The file specified does not exist.
System Action: The command line application
terminates.
User Response: Specify the fully qualified path
to a Java Virtual Machine.
CCL8818E The JVM specified is unsupported
Explanation: When trying to point to a Java
Virtual Machine using the CTGJAVA command,
the specified JVM is tested and determined to be
at an unsupported level.
System Action: The command line application
terminates.
User Response: Specify a supported Java
Virtual Machine to CTGJAVA.
CCL8819E The currently set JVM is
unsupported
Explanation: When trying to run a Java
application, the application launcher tests the
currently set JVM. It is determined to be at an
unsupported level.
System Action: The command line application
terminates.
94 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: Use the CTGJAVA command to
point to a supported Java Virtual Machine to
run.
CCL8820W Old IKeyman found in the JRE at
path. Unexpected errors may occur
Explanation: When launching IKeyman, the
application launcher found an old version of
IKeyman installed in the JRE. Unexpected errors
may occur within the IKeyman tool.
System Action: The command line application
continues.
User Response: If errors occur in the IKeyman
tool, delete the specified jar file and rerun the
launcher.
CCL9119 Attempt to get addressability to
an IPC queue element failed with
rc = value1
Explanation: On a Windows platform an
attempt to get addressability to a shared memory
element has failed for some operating system
reason.
System Action: The message is written to the
error log and the client tries to continue,
although attempts to reference this shared
memory element will result in a trap.
User Response: If the problem persists, contact
your service organization.
CCL9303 Memory allocation failed.
DosAllocMem return code: error
Explanation: The client was unable to allocate
the amount of memory required to hold the
returned data. The error value indicates the
failing return code.
System Action: The message is written to the
error log and the call fails.
User Response: Try reducing the amount of
data requested and try again. If the problem
persists contact your support organization.

CCL9304 Invalid call type (call_type)
Explanation: An invalid value (as indicated by
call_type) was specified for the ECI call type.
System Action: The message is written to the
error log and the call fails.
User Response: Correct the program so that a
supported value is specified for the ECI call type.
CCL9305 The commarea size specified
exceeds the length of data
supplied
Explanation: The value specified for the length
of the commarea is larger than the amount of
data supplied.
System Action: The message is written to the
error log and the call fails.
User Response: Correct the program so that the
specified length of the commarea is equal to, or
exceeds, the amount of data being passed to the
ECI.
CCL9306 The value specified for Extended
Mode (value) isinvalid
Explanation: An invalid value (as indicated by
value) has been specified for the ECI extended
mode parameter.
System Action: The message is written to the
error log and the call fails.
User Response: Correct the program so that a
supported value is specified for the extended
mode parameter.
CCL9307 The ECI version specified (version)
is not valid
Explanation: An invalid value (as indicated by
value) has been specified for the ECI version
parameter.
System Action: The message is written to the
error log and the call fails.
User Response: Correct the program so that a
supported value is specified for the ECI version
parameter.
CCL9313 Base address for returned
commarea allocated by
DosAllocMem is addr
Explanation: The client has successfully
allocated a buffer in memory to hold the data
returned in the commarea by the call to the ECI.
The value of addr indicates the address at which
the buffer has been allocated.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9314 eci_call_type = type
Explanation: The value type identifies the type
of call which has been requested.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9315 eci_program_name = progname
Explanation: The value progname identifies the
name of the program which is to be invoked by
this ECI call.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9316 eci_userid = userid
Explanation: The value userid identifies the
userid to be used for security checking.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9304 CCL9317
CCL9317 eci_password = password
Explanation: The value password identifies the
password to be used for security checking.
System Action: The message is written to the
trace file if tracing is enabled.
Messages 95

CCL9318 CCL9326
User Response: None.
CCL9318 eci_transid = tid
Explanation: The value tid identifies the TranID
specified for this call.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9319 User specified commarea length
was length
Explanation: The value length indicates an
explicit length for the commarea, as set by the
caller. A value of -1 indicates that no specific
value was provided and so the length of the user
supplied commarea will be used instead.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9320 eci_commarea_length = len
Explanation: A commarea length of len will be
used on the ECI call. It was either set explicitly
by the caller or else is taken as the length of the
commarea passed as input to the call.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9321 eci_timeout = seconds
Explanation: The value seconds specifies the
maximum time that the request from the
application should be allowed to take. This
parameter is provided for backwards
compatibility only and should normally be set to
0.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
96 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL9322 eci_extend_mode = mode
Explanation: The value mode specifies the
extended mode for this ECI call.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9323 eci_message_id = msgid
Explanation: The value msgid is a user-provided
reference to an asynchronous call.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9324 eci_luw_token = luwid
Explanation: The value luwid is an identifier for
a logical unit of work.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9325 eci_sysid = sysid
Explanation: The value sysid is reserved for
future use and should generally be left null.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9326 eci_version = version
Explanation: The value version specified the
version of the ECI for which the application is
coded. This should be set to the value
ECI_VERSION_1 or ECI_VERSION_1A.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.

CCL9327 eci_system_name = name
Explanation: The value name specifies the name
of the system to which the ECI call should be
directed.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9328 eci_userid2 = userid
Explanation: The value userid specifies a userid
to be used for security checking.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9329 eci_password2 = password
Explanation: The value password specifies a
password to be used for security checking.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9330 eci_tpn = tpn
Explanation: The value tpn specifies a
transaction name under which this program
should execute in the target system.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9331 Returned eci_return_code = rc
Explanation: The value rc is the return code
from the ECI call.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: Refer to the CICS Client/Server
Programming book for an explanation of the
error codes.
CCL9332 Returned eci_abend_code = abend
Explanation: The value abend is the abend code
for a failed program.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: Refer to the CICS Client/Server
Programming book for an explanation of the
error codes.
CCL9334 Returned eci_luw_token = luwid
Explanation: The value luwid is an identifier for
a logical unit of work. This is the value which
was returned by the call to the ECI.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9335 Returned eci_commarea_length =
length
Explanation: The value length specifies the
amount of data returned in the commarea after
the call to the ECI.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9336 Cammarea base address = addr,
length = length
Explanation: The call to the ECI has completed
successfully. The value of addr indicates the
location in memory of the returned commarea
and the value of length indicates the amount of
data returned in the commarea.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9327 CCL9336
Messages 97

CCL9337 CCL9500E
CCL9337 Error during ECI call. Commarea
not returned.
Explanation: The call to the ECI has completed
but an error was detected. No data is returned to
the calling application in the commarea.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: Information on the type of error
can be determined from earlier entries in the
trace log.
CCL9339 System count variable is name
Explanation: The value name indicates the
variable into which the number of systems found
will be written.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9340 List stem name is stemname
Explanation: The value stemname specifies the
stem of the variable into which the returned
system information is to be written.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9341 Number of systems found is count
Explanation: The value of count specifies the
number of systems found. Data can only be
returned for a number of systems up to the
implementation maximum (currently 100). If the
value of count is larger than the maximum
number specified then some data will have been
lost.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
98 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL9342 System name = sysname
(Description = desc)
Explanation: For each system returned to the
caller, the value sysname indicates the name of
the system and the value desc its associated
description.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9343 CICS_EciListSystems call
completed successfully
Explanation: The call has completed
successfully and control is being returned to the
calling program.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: None.
CCL9344 Error during CICS_EciListSystems
call. Return code: rc
Explanation: An error was encountered during
execution of the code. The value of rc indicates
the failing error code.
System Action: The message is written to the
trace file if tracing is enabled.
User Response: Refer to the CICS Client/Server
Programming book for an explanation of the
error codes.
CCL9500E Maximum number of Java
arguments exceeded
Explanation: The maximum number of
parameters that can be passed to the CTG has
been exceded.
System Action: The CTG service terminates.
User Response: Reduce the number of
arguments and try again.

CCL9501E Cannot load JNI dll: jvm.dll
Explanation: The service cannot find the Java
native runtime dll and is unable to start the
CTG.
System Action: The CTG service terminates.
User Response: Reinstall your Java Virtual
Machine
CCL9502E Service could not allocate memory
Explanation: Upon starting the CTG service
enough resources could not be allocated.
System Action: The CTG service terminates.
User Response: Free up some memory and try
again
CCL9503E Service could not create Java
Virtual Machine
Explanation: An error occured whilst trying to
start the Java Virtual Machine for the Gateway
service to run under. The options used when
trying to creat the JVM will be output when this
condition occurs.
System Action: The CTG service terminates.
User Response: Check the options supplied and
try again with different parameters
CCL9505E Cannot find class
com.ibm.ctg.server.JGate
Explanation: When attempting to start the CTG
service the required Java class could not be
found. This class can be found in the supplied
CTGSERVER.JAR.
System Action: The CTG service terminates.
User Response: Update your classpath and try
again.
CCL9506E No main() method found in class
com.ibm.ctg.server.JGate
Explanation: When attempting to start the CTG
service the main() method cannot be found
within the JGate class.
System Action: The CTG service terminates.
User Response: Reinstall the CICS Transaction
Gateway.
CCL9507E Out of memory
CCL9501E CCL9511E
Explanation: Whilst running the CTG service no
free memory was available for new resources.
System Action: The CTG service terminates.
User Response: If this occurs under expected
load then more memory may be needed to
satisfy the performance needs for the specific
CTG installation.
CCL9508E StartServiceControlDispatcher
failed
Explanation: An attempt to start the Windows
service control dispatcher failed.
System Action: The CTG service terminates.
User Response: Restart the machine and try to
start the service again.
CCL9510I Calling
StartServiceCtrlDispatcher.....
Explanation: The CTG service is attempting to
start the Windows Service control dispatcher.
System Action: This message is for information
only.
User Response: No further action is required
CCL9511E Unrecognized option: option
Explanation: The option specified is not
supported by the CTGSERVICE command line
executable.
System Action: The usage statement is
displayed
Messages 99

CCL9528E CCL9538E
User Response: Adjust the parameters you pass
to CTGSERVICE.EXE
CCL9528E Unable to install service name,
error: error message text
Explanation: Installation of the CTG service
failed. An error code describing why failure
occured is supplied.
System Action: The command line application
terminates
User Response: Check that the service isn’t
already installed and try again.
CCL9532E Service service name failed to stop
Explanation: When trying to stop the CTG
service before uninstallation an error occured.
System Action: The command line application
terminates.
User Response: Try to stop the service
manually and try the uninstall again.
CCL9533E OpenService failed: error message
text
Explanation: During an uninstall of the CTG
service the service could not be opened.
System Action: The command line application
terminates.
User Response: Check to see if the service is
installed and try again.
CCL9534E DeleteService failed: error message
text
Explanation: During an uninstall of the CTG
service the service could not be deleted.
System Action: The command line application
terminates.
User Response: Check to see if the service is
installed and try again.
100 CICS Transaction Gateway: CICS Transaction Gateway Messages
CCL9535E Failed to create AppParameters
sub-key
Explanation: Whilst attempting to create the
specified subkey to be used by the CTG in the
registry an error occured.
System Action: The command line application
terminates.
User Response: Restart the machine and try
again.
CCL9536E Failed to create AppParameters
string
Explanation: Whilst attempting to create the
specified string to be used by the CTG in the
registry an error occured.
System Action: The command line application
terminates.
User Response: Restart the machine and try
again.
CCL9537E Failed to save value of
AppParameters
Explanation: Whilst attempting to store the
parameters to be used by the CTG in the registry
an error occured.
System Action: The command line application
terminates.
User Response: Restart the machine and try
again.
CCL9538E Failed to create service: error
message text
Explanation: During an install of the CTG
service the service could not be created.
System Action: The command line application
terminates.
User Response: Check to see if the service is
already installed.

CCL9539E OpenSCManager failed: error
message text
Explanation: During an install of the CTG
service the Service Control Manager could not be
opened.
System Action: The command line application
terminates.
User Response: Restart the machine and try
again.
CTG6000I CTGARM - CTG Automatic
Restart Manager Batch Utility
Explanation: The CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) is starting. This message is the first of a
series of messages generated by the utility.
System Action: The utility continues.
User Response: For information only.
CTG6001I End of CTGARM - CTG
Automatic Restart Manager Batch
Utility
Explanation: The CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) has completed. This message marks the
end of a series of messages generated by the
utility.
System Action: The utility ends.
User Response: For information only.
CTG6002I Parameters processed:
Explanation: This is a header line before a list
of parameters read by the utility. There will
follow three messages, one for each parameter
passed.
System Action: If all the parameters are valid,
the utility will continue, otherwise an error
message will be issued and the utility will end.
User Response: For information only.
CTG6003I COMMAND: [value]
Explanation: This is first parameter passed to
ctgarm, and is evaluated from the first letter of
the parameter. Valid values are: Register and
Deregister.
System Action: If the parameter is valid, the
utility will continue, otherwise an error message
will be issued and the utility will end.
User Response: For information only.
CTG6004I ARM_ID: [value]
Explanation: This is second parameter passed to
ctgarm. Valid values are between 1 and 16
characters. Valid characters are the uppercase
alphabetic characters, the numbers 0 through 9
and the special characters: $, #, @, and
underscore (_).
System Action: If the parameter is valid, the
utility will continue, otherwise an error message
will be issued and the utility will end.
User Response: For information only.
CTG6005I ARM_TYPE: [value]
Explanation: This is the optional third
parameter passed to ctgarm. Valid values are
between 1 and 8 characters. Valid characters are
the uppercase alphabetic characters, the numbers
0 through 9 and the special characters: $, #, @,
and underscore (_). If the parameter was absent,
then it will default to the value SYSLVL2. See the
Administration book for details.
System Action: If the parameter is valid, the
utility will continue, otherwise an error message
will be issued and the utility will end.
User Response: For information only.
CTG6006I Results are:
CCL9539E CTG6006I
Explanation: This is a header line following a
message describing the call to Automatic Restart
Manager. There will follow two messages,
specifying the return code and reason code
values from the call. A further message will
indicate the outcome of the call.
Messages 101

CTG6007I CTG6015E
System Action: If the results are acceptable, the
utility will continue, otherwise it will end.
User Response: Refer to the z/OS MVS
Programming: Sysplex Services Reference manual for
information on unexplained return and reason
codes.
CTG6007I Return code: [value]
Explanation: The return code is given as a
hexadecimal value. Generally a successful return
code is 00 or 04.
System Action: If the results are acceptable, the
utility will continue, otherwise it will end.
User Response: Refer to the z/OS MVS
Programming: Sysplex Services Reference manual for
explanations of return code values.
CTG6008I Reason code: [value]
Explanation: The reason code is given as a
hexadecimal value.
System Action: If the results a acceptable, the
utility will continue, otherwise it will end.
User Response: Refer to the z/OS MVS
Programming: Sysplex Services Reference manual for
explanations of reason code values.
CTG6010S Severe Error - Cannot read
parameters
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) has an internal error reading the passed
parameters.
System Action: The utility will not run.
User Response: Contact your service
organisation.
CTG6011E Error - Too many parameters
passed
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) takes either 1,2 or 3 parameters. See
other messages for the command format.
102 CICS Transaction Gateway: CICS Transaction Gateway Messages
System Action: The parameters were incorrect,
and the utility will not run.
User Response: Check the format of the
command used and retry.
CTG6012E Error - Empty parameter passed
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) takes either 1,2 or 3 parameters. See
other messages for the command format.
System Action: The parameters were incorrect,
and the utility will not run.
User Response: Check the format of the
command used and retry.
CTG6013E Error - missing parameters
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) takes either 1,2 or 3 parameters. See
other messages for the command format.
System Action: The parameters were incorrect,
and the utility will not run.
User Response: Check the format of the
command used and retry.
CTG6014E Bad command, only ″Register″
and ″Deregister″ supported
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) takes either R or D as its first
parameter. See other messages for the command
format.
System Action: The parameters were incorrect,
and the utility will not run.
User Response: Check the format of the
command used and retry.
CTG6015E Ready not accepted by ARM - see
reason codes
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Ready function of Automatic

Restart Manager (ARM) as one of the last phases
of registering with ARM. ARM rejected the call.
System Action: The utility will terminate.
User Response: An explanation of the reason
code returned by the Ready request to ARM can
be found in the z/OS MVS Programming: Sysplex
Services Reference manual.
CTG6016E Registration failed - see reason
codes
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. ARM rejected the
call.
System Action: The utility will terminate.
User Response: An explanation of the reason
code returned by the Registration request to ARM
can be found in the z/OS MVS Programming:
Sysplex Services Reference manual.
CTG6017E Wait for predecessors failed - see
reason codes
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Wait function of Automatic
Restart Manager (ARM) as the Register request to
ARM indicated that this was a restart. ARM
rejected the call.
System Action: The utility will terminate.
User Response: An explanation of the reason
code returned by the Wait request to ARM can be
found in the z/OS MVS Programming: Sysplex
Services Reference manual.
CTG6018E Deregistration failed - see reason
codes
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Deregistration function of
Automatic Restart Manager (ARM) to deregister
with ARM. ARM rejected the call. This is a
non-fatal error.
CTG6016E CTG6022E
System Action: The utility will terminate.
User Response: An explanation of the reason
code returned by the Deregister request to ARM
can be found in the z/OS MVS Programming:
Sysplex Services Reference manual.
CTG6020E Deregistration failed - was not
registered
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Deregistration function of
Automatic Restart Manager (ARM) to deregister
with ARM. ARM rejected the call because this job
was not registered with ARM.
System Action: The utility will terminate.
User Response: No further action is required.
CTG6021E Registration failed - ARM_ID
already in use
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. ARM rejected the
call because the ARM_ID was not unique in the
sysplex.
System Action: The utility will terminate.
User Response: Choose a sysplex unique id and
re-run the utility.
CTG6022E Registration failed - ARM_ID is
invalid
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. ARM rejected the
call because the ARM_ID did not conform to the
character restrictions.
System Action: The utility will terminate.
User Response: Check the value in the ARM_ID
parameter against the restrictions given by other
messages.
Messages 103

CTG6023E CTG6032I
CTG6023E Registration / Deregistration
failed - ARM is not running
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. The call to ARM
failed because ARM was not active on the
sysplex.
System Action: The utility will terminate.
User Response: Investigate why ARM is not
running.
CTG6024E Registration / Deregistration
failed - This is not a started job
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. ARM rejected the
call because only started jobs can register.
System Action: The utility will terminate.
User Response: The utility may have been
called from the USS command line or as part of
a USS script. The utility can run successfully
only when called from BPXBATCH with a PGM=
parameter. Refer to the CTG Administration book
for JCL examples.
CTG6025E Registration failed - ARM_TYPE
is invalid
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. ARM rejected the
call because the ARM_TYPE did not conform to
the character restrictions.
System Action: The utility will terminate.
User Response: Check the value in the
ARM_TYPE parameter against the restrictions
given by messages.
104 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG6026E Error - ARM_ID is too long -
maximum of 16 characters.
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) Registration command takes a required
parameter (ARM_ID) that is up to 16 characters
long. See other messages for the command
format.
System Action: The parameter is incorrect, and
the utility will not run.
User Response: Check the format of the
command used and retry.
CTG6027E Error - ARM_TYPE is too long -
maximum of 8 characters.
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) Registration command takes an optional
parameter (ARM_TYPE) that is up to 8
characters long. See other messages for the
command format.
System Action: The parameter is incorrect, and
the utility will not run.
User Response: Check the format of the
command used and retry.
CTG6031I This is first time register with
ARM
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. ARM has
accepted the registration, and this is not a
restarted job.
System Action: The utility completes
successfully.
User Response: For information only.
CTG6032I This is a re-started job, so wait for
any predecessors
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility

(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM. ARM has
accepted the registration, but this is a restarted
job. The utility must now call ARM with the Wait
function to allow any predecessor jobs to restart
before continuing.
System Action: The utility continues.
User Response: For information only.
CTG6033I Deregistering from ARM
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) will call the Deregistration function of
Automatic Restart Manager (ARM) to deregister
with ARM.
System Action: The utility continues.
User Response: For information only.
CTG6034I Registering with ARM
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) will call the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM.
System Action: The utility continues.
User Response: For information only.
CTG6035I Telling ARM we are ready
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) will call the Ready function of
Automatic Restart Manager (ARM) as the last
phase of registering with ARM as a restarted job.
System Action: The utility continues.
User Response: For information only.
CTG6036I Successfully deregistered with
ARM
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
CTG6033I CTG6052E
(ctgarm) called the Deregistration function of
Automatic Restart Manager (ARM) to deregister
with ARM.
System Action: The utility continues.
User Response: For information only.
CTG6037I Successfully registered with ARM
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) called the Registration function of
Automatic Restart Manager (ARM) as the first
phase of registering with ARM.
System Action: The utility continues.
User Response: For information only.
CTG6051S System Error with CSVQUERY,
RC=[value]
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) uses the CSVQUERY macro to check if
it has been APF authorized. The call to do this
has failed with the return code [value].
System Action: The utility terminates.
User Response: This is a severe error and
should be reported to the service team.
CTG6052E Error - ctgarm is not APF
Authorized.
Explanation: CICS Transaction Gateway
Automatic Restart Manager Batch Utility
(ctgarm) must be APF authorized in order to
register with ARM. This should happen during
installation.
System Action: The utility terminates.
User Response: See the installation instructions
in the Administration book for details of how to
APF authorize ctgarm.
Messages 105

CTG6100E CTG6106E
CTG6100E The installation cannot continue
as the operating system of this
machine (machine OS Version) does
not reach the pre-requisite level
(minimum OS Version).
Explanation: The operating system level is not
supported.
System Action: The install terminates.
User Response: Refer to the CTG
Administration book for your system to
determine the supported levels of operating
system.
CTG6101W Not enough primary allocation
space in directory directory name to
install the product. If you have
enough secondary allocation
space, the installation may still
succeed.
Explanation: On the z/OS operating system, the
size of directory space can be expanded
automatically as disk space is used up. The space
currently allocated to directory name is insufficient
to continue the installation, but may be able to
expand as required.
System Action: The script will prompt the user
with the option to continue or terminate.
User Response: Either expand the disk space
allocation for the given directory, or continue
with the installation and check for other possible
errors due to the limited space.
CTG6102E Not enough space in directory
directory name to unpack the
product.
Explanation: The space currently allocated to
directory name is insufficient to continue the
installation.
System Action: The install will terminate.
User Response: Expand the disk space
allocation for directory name and retry the install.
106 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG6103E Command command name cannot
be found in your PATH.
Explanation: The install requires the use of the
command: command name, but this is not in the
current PATH.
System Action: The install will terminate.
User Response: Identify where this command is
on your system. Add its location to your PATH
and retry the install. See the Problem
Determination section in the CTG Administration
book for your system for further information.
CTG6104E You must be logged in as root to
install this product. Log in as root
and try again.
Explanation: On most platforms you will
require super user or root authority to complete
the installation.
System Action: The install will terminate.
User Response: Log in as root or su to superuser
and retry the install.
CTG6105W Install could not change to
codepage %s1 - the installation
may not be valid.
Explanation: When installing in non-US locales,
the installation will attempt to convert scripts to
a codepage suitable for the current locale. This
has failed.
System Action: The install continues, but the
scripts will be left in the default codepage.
User Response: Check the following message to
determine the reason for failure, for example,
unsupported language and code set combination.
Try running the ctgmsgs command to set the
language and code set you require.
CTG6106E Language language code is not
recognized. Use command ctgmsgs
to list the recognized languages.
Explanation: CICS Transaction Gateway
supports a number of language and code set
combinations, but the specified language code is

not supported on this platform.
System Action: The message language will not
be changed.
User Response: Run the ctgmsgs command with
the -? parameter to get a list of supported
language and code set combinations. Choose the
combination that best meets your requirements
and retry with that combination.
CTG6107E Code set code set is not recognized.
Use command ctgmsgs to list the
recognized code sets.
Explanation: CICS Transaction Gateway
supports a number of language and code set
combinations, but the specified code set is not
supported on this platform.
System Action: The message language will not
be changed.
User Response: Run the ctgmsgs command with
the -? parameter to get a list of supported
language and code set combinations. Choose the
combination that best meets your requirements
and retry with that combination.
CTG6108E Adobe Acrobat Reader not found.
Explanation: The documentation for CICS
Transaction Gateway is provided in a PDF file,
and Adobe Acrobat reader was not found on the
system.
System Action: The ctgdoc utility terminates.
User Response: Either install Adobe Acrobat
reader, if it is available for this platform, or
identify a reader for PDF files and use this to
view the documentation which is available in the
/docs directory, or copy the PDF file
to a platform that supports Adobe Acrobat
reader.
CTG6109E The JVM is not at the required
level to run this application.
Explanation: The Java applications supplied
with CICS Transaction Gateway require a
minimum level of JVM.
CTG6107E CTG6112W
System Action: The CICS Transaction Gateway
will not start.
User Response: See the Administration book for
details of the versions of Java supported. Install
the correct level of Java and add access to it from
the PATH.
CTG6110E File ctgenvvar not found. Create it
by copying ctgenvvarsamp and
editing it to match your
environment
Explanation: CICS Transaction Gateway on
z/OS uses the ctgenvvar script to initialize
environment variables before executing its Java
component.
System Action: The CICS Transaction Gateway
will not start.
User Response: See the Administration book for
details on configuring the Gateway and creating
ctgenvvar.
CTG6111I File ctgenvvar found. Using the
configuration in script ctgenvvar to
start up the application.
Explanation: CICS Transaction Gateway on zOS
uses the ctgenvvar script to initialize environment
variables before executing its Java component.
System Action: The script will continue, using
the ctgenvvar values.
User Response: For information only.
CTG6112W To configure CICS Transaction
Gateway for use with RACF
userid and password
authentication, a user with READ
access to the
BPX.FILEATTR.PROGCTL
FACILITY class will need to run
the command [unix command].
Explanation: The install script attempts to set
extended attributes required to run with RACF
userid and password authentication. If the user
does not have authority to do this the message is
issued as a warning.
Messages 107

CTG6113W CTG8202E
System Action: The script continues without
setting the extended attributes.
User Response: If you wish to configure CTG
for RACF authentication, then an authorized user
will need to enter this [unix command],
otherwise no further action is necessary. See the
Administration book or the z/OS UNIX System
Services Planning book for more information.
CTG6113W To configure CICS Transaction
Gateway for use with z/OS
Automatic Restart Manager, a user
with authority to update RACF
group BPX.FILEATTR.APF will
need to run the command [unix
command].
Explanation: The install script attempts to set
extended attributes required to run the ctgarm
command. If the user does not have authority to
do this the message is issued as a warning.
System Action: The script continues without
setting the extended attributes.
User Response: If you wish to use ARM, then
an authorized user will need to enter this [unix
command], otherwise no further action is
necessary. See the Administration book or the
z/OS UNIX System Services Planning book for
more information.
CTG6114E CICS Transaction Gateway has
not been fully installed. Run the
command setup command to
complete the installation.
Explanation: Part of the installation process is
to run the setup command, but this has not been
completed satisfactorily.
System Action: The script terminates.
User Response: Refer to the CTG
Administration book for more information on
installing the product.
108 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG6115S There is an internal problem
installing the CICS Transaction
Gateway.
Explanation: The ctgsetup command has failed
to unlock this installation of the CICS
Transaction Gateway. The messages following
may indicate why it failed.
System Action: The script terminates.
User Response: Refer to the problem
determination section of CTG Administration
book. If this does not resolve the problem,
contact your service representative with the
information.
CTG8200E No message available for message
id {0}
Explanation: The message id indicated could
not be located within the message file.
System Action: No action has been taken.
User Response: Contact your service
representative with the information.
CTG8201E Unable to open a connection to
gateway {0}. Exception
message={1}
Explanation: An exception was thrown when
trying to open a connection to the CTG Server at
the specified URL. The exception message is
provided.
System Action: The requested action cannot be
completed.
User Response: The exception may provide
more information into the problem.
CTG8202E Exception occurred trying to
authenticate with gateway {0}.
Exception message={1}
Explanation: An exception was thrown when
trying to authenticate the client with the CTG
Server at the specified URL. The exception
message is provided.

System Action: The requested action cannot be
completed.
User Response: The exception may provide
more information into the problem.
CTG8203E Unexpected gateway rc={0} trying
to authenticate with gateway {1}
Explanation: An unexpected return code was
received when trying to authenticate the client
with the CTG server at the specified URL.
System Action: The requested action cannot be
completed.
User Response: The return code may provide
more information into the problem.
CTG8204E Gateway {0} has security protocols
in place not recognized by this
program
Explanation: CTGAdmin cannot handle the
security protocols in place on the CTG Server at
the specified URL.
System Action: The requested action cannot be
completed.
User Response: Obtain a later version of
ctgadmin.jar, or disable the protocols at Gateway
{0}.
CTG8205E Unknown security protocol {0} in
Gateway {1} reported a failure
rc={2}
Explanation: The indicated security protocol,
unknown to CTGAdmin, reported a failure of the
specified return code.
System Action: The requested action cannot be
completed.
User Response: Obtain a later version of
ctgadmin.jar, or disable the protocols at Gateway
{0}.
CTG8203E CTG8209E
CTG8206E Unexpected gateway rc={0} trying
to send request to gateway {1}
Explanation: An unexpected return code was
received trying to send the request from the
authenticated client.
System Action: The requested action cannot be
completed.
User Response: The return code may provide
more information into the problem.
CTG8207E Unable to initialize with
authenticated gateway {0}. rc={1}
Explanation: An unexpected return code was
received trying to initialize with the CTG server
from an authenticated client at the specified
URL.
System Action: The requested action cannot be
completed.
User Response: The return code may provide
more information into the problem.
CTG8208E Exception occurred trying to send
request to gateway {0}. Exception
message={1}
Explanation: An exception was thrown when
trying to send a request from an authenticated
client to the CTG Server at the specified URL.
The exception message is provided.
System Action: The requested action cannot be
completed.
User Response: The exception may provide
more information into the problem.
CTG8209E Unexpected rc={0} sending request
to gateway {1}
Explanation: An unexpected return code was
received trying to send a request to the CTG
server from an authenticated client at the
specified URL.
System Action: The requested action cannot be
completed.
User Response: The return code may provide
Messages 109

CTG8210E CTG8218E
more information into the problem.
CTG8210E The gateway {0} reports no
management server located
Explanation: The CTG server at the specified
URL was unable to locate its management server.
System Action: The requested action cannot be
completed.
User Response: Obtain a trace from the CTG
Server and contact your service representative.
CTG8211E The gateway {0} sent back
information which this client
cannot read
Explanation: CTGAdmin cannot handle
information sent by the CTG server at the
specified URL.
System Action: The requested action cannot be
completed.
User Response: Ensure that the Java level on
the client is at least as high as that on the server.
Also check that you have the latest version of
ctgadmin.jar installed.
CTG8212E Tag ″{0}″ must be specified
Explanation: The mandatory tag was not
specified.
System Action: The requested action cannot be
completed.
User Response: Reissue the command,
specifying the tag.
CTG8213E An unexpected error occurred
processing tag ″{0}″
Explanation: An unexpected error occurred
when processing the specified tag.
System Action: The requested action cannot be
completed.
User Response: Contact your service
representative.
110 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG8214E Tag ″{0}″ cannot be specified more
than once
Explanation: The specified tag appears more
than once in the request; this is not allowed.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8215E Tag ″{0}″ is not valid
Explanation: The specified tag is not
recognized.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8216E Tag ″{0}″ must be prefixed with -
Explanation: A parameter was provided but did
not start with a minus sign
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8217E URL ″{0}″ for tag ctg is not valid
Explanation: The URL specified in the ctg tag is
not a valid URL.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8218E URL ″{0}″ did not specify the TCP
protocol
Explanation: The URL given in the ctg tag did
not specify the TCP protocol. Currently
CTGAdmin supports only the TCP protocol.
System Action: The requested action cannot be
completed.

User Response: Correct the request and try
again. The form of the ctg tag is
-ctg=tcp://mygateway.com:2810
CTG8219E Action ″{0}″ specified is not valid
Explanation: CTGAdmin did not recognize the
specified action.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again. Refer to help for a list of valid actions.
CTG8220E No recognized tags for action ″{0}″
specified
Explanation: This action requires tags, but no
valid ones were specified.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8221E Value for tag ″{0}″ must be
numeric
Explanation: The value for the specified tag was
not a number and is required to be a number.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8222E Tag ″{0}″, value {1} outside range
of {2}-{3}
Explanation: The value for the specified tag was
not within the range specified by {2}-{3}.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8219E CTG8226E
CTG8223E Cannot specify the tag
fulldatadump with dumpoffset or
truncationsize
Explanation: For the setgwtrace action you
cannot specify the fulldatadump tag with the
dumpoffset tag or the truncationsize tag.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again. Specify fulldatadump if you want the
complete contents of the dump. Specify
dumpoffset, or truncationsize, or both, if you
want a partial dump.
CTG8224E IP address or hostname not
authorized for gateway {0}
Explanation: The client machine is not
authorized to perform administrative commands
on the specified URL.
System Action: The requested action cannot be
completed.
User Response: Check that the host from which
you are issuing the command appears in the list
of authorized hosts at the Gateway that you are
attempting to administer (configuration tool,
TCPAdmin panel).
CTG8225E Tag ″{0}″, value {1} is below
minimum value of {2}
Explanation: The value for the specified tag was
too low and cannot be used.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8226E Gateway {0} is not restricted. URL
cannot be used
Explanation: The specified URL does not refer
to the TCPAdmin protocol handler but refers to a
standard TCP protocol handler.
Messages 111

CTG8227E CTG9602I
System Action: The requested action cannot be
completed.
User Response: specify the URL for the
TCPAdmin handler and reissue the request.
CTG8227E Exception returned from gateway
{0}. Exception message={1}
Explanation: An exception was returned from
the CTG Server at the specified URL.
System Action: The requested action cannot be
completed.
User Response: The exception message will
provide more information on the problem.
CTG8228E Specified tag(s) ″{0}″ unknown for
requested action
Explanation: The specified tag is not
recognized.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG8229E Unexpected rc={0} trying to
authenticate with gateway {1}
Explanation: An unexpected return code was
received when trying to authenticate the client
with the CTG server at the specified URL.
System Action: The requested action cannot be
completed.
User Response: The return code may provide
more information into the problem.
CTG8230E The gateway {0} sent back an
exception that this client cannot
read
Explanation: The CTG Server at the URL
specified tried to send an exception back which
cannot be handled by CTGAdmin.
System Action: The requested action cannot be
completed.
112 CICS Transaction Gateway: CICS Transaction Gateway Messages
User Response: Ensure that the Java level on
the client is at least as high as that on the server.
Also check that you have the latest version of
ctgadmin.jar installed.
CTG8231E JNI Trace file name must be
specified
Explanation: For the setjnitrace action, the tfile
tag was specified but no value was given. A
value must be specified.
System Action: The requested action cannot be
completed.
User Response: Correct the request and try
again.
CTG9600I ResultSet not supported
Explanation: The ResultSet Record type is not
supported by the CICS resource adapters.
System Action: System action is not required.
User Response: You are attempting to get a
ResultSet, which is not supported by the CICS
resource adapters.
CTG9601E This connection is already closed
Explanation: The connection has already been
closed and so cannot be closed again.
System Action: System action is not required.
User Response: You are attempting to close a
connection that has already been closed.
CTG9602I RecordFactory not supported
Explanation: The CICS resource adapters do not
provide or support the use of a RecordFactory
object as defined within the J2EE/CA
Specification.
System Action: System action is not required.
User Response: You are attempting to get a
reference to a RecordFactory, which is not
supported by the CICS resource adapters.

CTG9603E ConnectionManager has returned
an invalid connection
Explanation: The connection returned by the
ConnectionManager is not of the correct type for
use with the CICS resource adapters. This is an
internal error.
System Action: System action is not required.
User Response: The CICS Resource Adapter
was returned a connection that was either null,
or not of the correct type.
CTG9604I This form of execute is not
supported
Explanation: The CICS resource adapters only
support the two parameter version of execute()
as prior knowledge of the output Record object is
needed in order to store the reply from CICS.
System Action: System action is not required.
User Response: Please recode the application to
use the two parameter variant of execute() as
defined in the javadoc.
CTG9605E ManagedConnection cannot be
used, it is in an unrecoverable
state
Explanation: Due to an unrecoverable error the
ManagedConnection object your application is
using has become corrupted and cannot be used
for any further interactions with CICS.
System Action: System action is not required.
User Response: User action above.
CTG9606I Feature not supported by ECI
resource adapter.
Explanation: The method being called is not
supported by the ECI resource adapter.
System Action: System action is not required.
User Response: Please adjust the application, as
this feature of the Connector specification is not
supported by the ECI resource adapter.
CTG9603E CTG9616E
CTG9607E Transaction failed to commit,
rolled back instead.
Explanation: Due to some error the transaction
failed to commit on CICS and so a rollback was
carried out to back out any work done within
the transaction.
System Action: The system has attempted to
commit the transaction but cannot do so. The
transaction has therefore been rolled back.
User Response: User action above.
CTG9610E Transaction already started on
ECIManagedConnection.
Explanation: A local transaction has already
been started on the ECIManagedConnection so
you may not start another. Only one local
transaction per ECIManagedConnection at any
one time is supported by the ECI resource
adapter.
System Action: System action is not required.
User Response: User action above.
CTG9611E Transaction not started on
ECIManagedConnection.
Explanation: A local transaction has not been
started on the ECIManagedConnection so any
calls to commit() or rollback() will fail.
System Action: System action is not required.
User Response: The local transaction has not
been started, so cannot commit.
CTG9616E Transaction failed to commit or
roll back.
Explanation: A request was made, but failed,
possibly due to a communications error.
System Action: System action is not required.
User Response: Due to an error, this transaction
cannot be committed or rolled back.
Messages 113

CTG9617E CTG9624E
CTG9617E ECI connection closed.
Explanation: Access to this ECIConnection is no
longer allowed as it has been closed. A new
ECIConnection must be acquired for any further
interaction to occur with CICS.
System Action: System action is not required.
User Response: This connection is closed, no
further work through this handle is allowed.
CTG9618E Cannot associate connection with
ECIManagedConnection. Supplied
Connection is null.
Explanation: When trying to associate a
connection with an ECIManagedConnection the
connection type must be ECIConnection. This is
an internal error.
System Action: System action is not required.
User Response: Connection handle supplied is
null.
CTG9619E Cannot associate connection with
ECIManagedConnection. Not of
type ECIConnection.
Explanation: When trying to associate a
connection with an ECIManagedConnection the
connection type must be ECIConnection. This is
an internal error.
System Action: System action is not required.
User Response: The Connection handle is not of
the correct type.
CTG9620E Connection returned by
ConnectionManager not of type
ECIConnection.
Explanation: The ConnectionManager has not
returned an ECIConnection object from the
allocateConnection() method.
System Action: System action is not required.
User Response: The Connection handle
returned is not of the correct type.
114 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG9621E ConnectionSpec supplied is not of
type ECIConnectionSpec.
Explanation: The ECI resource adapter only
supports ConnectionSpec objects of the type
ECIConnectionSpec.
System Action: System action is not required.
User Response: The ConnectionSpec handle is
not of the correct type.
CTG9622E ConnectionRequestInfo object is
not of type
ECIConnectionRequestInfo.
Explanation: The ConnectionRequestInfo object
being supplied to the ECI resource adapter is not
of the correct type. This is an internal error.
System Action: System action is not required.
User Response: The ConnectionRequestInfo
handle is not of the correct type.
CTG9623E ConnectionManager supplied is
null.
Explanation: The ConnectionManager supplied
to the ECIConnectionFactory is null. In a
managed environment this is a internal error to
the environment. In a nonmanaged environment
you must not supply a null ConnectionManager
to the ECIConnectionFactory constructor.
System Action: System action is not required.
User Response: The ConnectionManager handle
is null.
CTG9624E ECIInteraction closed.
Explanation: You cannot do any further work
with this ECIInteraction object as it has been
closed.
System Action: System action is not required.
User Response: The ECIInteraction has been
closed, further work is not allowed.

CTG9625E ECIConnection used during
interaction is null.
Explanation: The ECIConnection object
associated with the current ECIInteraction object
is null so the interaction cannot continue. This is
an internal error.
System Action: System action is not required.
User Response: The Connection handle is null
for this interaction.
CTG9626E Connection associated with
ECIInteraction not of type
ECIConnection.
Explanation: The ECIConnection that is being
used by your ECIInteraction is not of the correct
type. This is an internal error.
System Action: System action is not required.
User Response: The Connection handle for this
interaction is not of the correct type.
CTG9627E IOException occurred when
writing to the Output Record.
Explanation: An I/O exception was thrown by
the record when the resource adapter attempted
to populate it with the relevant information. The
record exception is linked to this one.
System Action: System action is not required.
User Response: User action above.
CTG9628E InteractionSpec passed to
execute() not of type
ECIInteractionSpec.
Explanation: Only InteractionSpec objects of the
type ECIInteractionSpec can passed to the
ECIInteraction.execute() method.
System Action: System action is not required.
User Response: InteractionSpec passed in to the
execute method is not of the correct type.
CTG9625E CTG9632E
CTG9629E InteractionSpec passed to
execute() is null.
Explanation: When calling
ECIInteraction.execute() a non null
ECIInteractionSpec must be supplied at all times.
System Action: System action is not required.
User Response: Null was passed to the
ECIInteractionSpec.execute method.
CTG9630E IOException occurred in
communication with CICS.
Explanation: During an interaction an
IOException has occurred when communicating
with a CICS server.
System Action: System action is not required.
User Response: User action above.
CTG9631E Error occurred during interaction
with CICS. Error Code=
Explanation: During an interaction with a CICS
server a known error has occurred in the
underlying CICS Transaction Gateway runtime.
The supplied error code can be referenced in the
CICS Transaction Gateway documentation. This
is an internal error.
System Action: System action is not required.
User Response: User action above.
CTG9632E SYNC_SEND
/SYNC_SEND_RECEIVE not
supported when reply to previous
SYNC_SEND is pending.
Explanation: If a SYNC_SEND interaction has
been executed and no matching SYNC_RECEIVE
has been carried out the a reply is pending so no
further SYNC_SEND/ SYNC_SEND_RECEIVE
interactions are allowed until a SYNC_RECEIVE
is executed.
System Action: System action is not required.
User Response: User action above.
Messages 115

CTG9633E CTG9641E
CTG9633E SYNC_RECEIVE attempted
without corresponding
SYNC_SEND.
Explanation: In order to receive a reply from
CICS using a SYNC_RECEIVE Interaction a
SYNC_SEND Interaction must first be executed.
System Action: System action is not required.
User Response: User action above.
CTG9634E Input record does not implement
javax.resource.spi.Streamable
interface.
Explanation: Input record objects supplied to
the ECIInteraction.execute() method must
support the javax.resource.spi.Streamable
interface.
System Action: System action is not required.
User Response: User action above.
CTG9635E Input record is null.
Explanation: When specifying an
InteractionVerb of SYNC_SEND or
SYNC_SEND_RECEIVE a non null input Record
object must be supplied as input to CICS.
System Action: System action is not required.
User Response: User action above.
CTG9636E Output record does not
implement
javax.resource.spi.Streamable
interface.
Explanation: Output record objects supplied to
the ECIInteraction.execute() method must
support the javax.resource.spi.Streamable
interface.
System Action: System action is not required.
User Response: User action above.
116 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG9637E Output record is null.
Explanation: When specifying an
InteractionVerb of SYNC_RECEIVE or
SYNC_SEND_RECEIVE a non null output
Record object must be supplied to hold the reply
from CICS.
System Action: System action is not required.
User Response: User action above.
CTG9638E Transaction Abend occurred in
CICS. Abend Code=
Explanation: During the Interaction with CICS
a Transaction Abend occurred on the server. The
supplied code is that which is returned by CICS.
System Action: System action is not required.
User Response: User action above.
CTG9639E Unable to perform action,
connection is closed
Explanation: The EPIConnection has been
closed and can no longer be used.
System Action: System action is not required.
User Response: Connection is closed, no further
work possible.
CTG9640E No connection was returned by
ConnectionManager
Explanation: The ConnectionManager did not
return an EPIConnection for use by the
application.
System Action: System action is not required.
User Response: No connection returned by the
ConnectionManager.
CTG9641E Invalid connection was returned
by ConnectionManager
Explanation: An unusable Connection object
was returned by the ConnectionManager.
System Action: System action is not required.

User Response: Invalid connection was
returned by ConnectionManager.
CTG9642E Invalid ConnectionSpec was
supplied, must be an
EPIConnectionSpec instance
Explanation: Only ConnectionSpecs of the type
EPIConnectionSpec are accepted in the
getConnection() method of
EPIConnectionFactory.
System Action: System action is not required.
User Response: Invalid ConnectionSpec was
supplied, must be an EPIConnectionSpec
instance.
CTG9643E Unable to perform action,
interaction is closed
Explanation: The EPIInteraction is closed so no
further work can be carried out on it.
System Action: System action is not required.
User Response: Connection is closed, no further
work possible.
CTG9644E No EPIInteractionSpec supplied
Explanation: An EPIInteractionSpec must be
supplied when EPIConnection.execute() is called.
System Action: System action is not required.
User Response: User action above.
CTG9645E Invalid InteractionSpec was
supplied, must be an
EPIInteractionSpec instance
Explanation: An EPIInteractionSpec must be
supplied when EPIConnection.execute() is called.
System Action: System action is not required.
User Response: User action above.
CTG9642E CTG9649I
CTG9646E Invalid connection passed to
associate connection method by
application server
Explanation: When attempting to associate a
Connection object with an
EPIManagedConnection the incorrect type was
used. The EPI resource adapter only supports
EPIConnection objects being passed to the
associateConnection() method.
System Action: System action is not required.
User Response: User action above.
CTG9647E A null connection was passed to
associate connection method by
application server
Explanation: When attempting to associate a
Connection object with an
EPIManagedConnection the incorrect type was
used. The EPI resource adapter only supports
EPIConnection objects being passed to the
associateConnection() method.
System Action: System action is not required.
User Response: A null connection was passed
to associateConnection() method by the
application server.
CTG9648I Local transactions not supported
Explanation: The EPI resource adapter does not
support any transactional interfaces. Any attempt
to use them will throw an exception.
System Action: System action is not required.
User Response: User action above.
CTG9649I XAResource not supported
Explanation: The EPI resource adapter does not
support any transactional interfaces. Any attempt
to use them will throw an exception.
System Action: System action is not required.
User Response: User action above.
Messages 117

CTG9650E CTG9658E
CTG9650E Streamable input record
information does not contain the
correct amount of data
Explanation: The amount of data stored in the
input Record object does not correspond to the
amount required for the currently defined screen
size.
System Action: System action is not required.
User Response: Streamable input record
information does not contain the correct amount
of data.
CTG9651E Input record is of unknown type
and cannot be used
Explanation: Input record objects supplied to
EPIInteraction.execute() must implement the
javax.resource.spi.Streamable interface in order to
be used by the EPI resource adapter.
System Action: System action is not required.
User Response: User action above.
CTG9652E Output record is of unknown type
and cannot be used
Explanation: Output record objects supplied to
EPIInteraction.execute() must implement the
javax.resource.spi.Streamable interface in order to
be used by the EPI resource adapter.
System Action: System action is not required.
User Response: User action above.
CTG9653E No output record was given and
one was expected
Explanation: When executing a
SYNC_RECEIVE or SYNC_SEND_RECEIVE an
output record must be supplied to hold the reply
from CICS.
System Action: System action is not required.
User Response: User action above.
118 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG9654E No input record was given and
one was expected
Explanation: When executing a SYNC_SEND or
SYNC_SEND_RECEIVE an input record must be
supplied to hold the data to be sent to CICS.
System Action: System action is not required.
User Response: User action above.
CTG9655E LogonLogoff class threw an
exception which is linked to this
one
Explanation: An exception was thrown whilst
accessing the LogonLogoff class specified. The
original exception can be accessed using the
getLinkedException method.
System Action: System action is not required.
User Response: User action above.
CTG9656E LogonLogoff class could not be
found
Explanation: The LogonLogoff class specified
could not be found in the current CLASSPATH.
Check that any required files are in your systems
CLASSPATH.
System Action: System action is not required.
User Response: User action above.
CTG9657E LogonLogoff class found but
could not be instantiated
Explanation: An error occurred whilst trying to
instantiate the LogonLogoff class specified.
System Action: System action is not required.
User Response: User action above.
CTG9658E No authority to create
LogonLogoff Class
Explanation: Your application does not have the
required authorization to create the specified
LogonLogoff class.
System Action: System action is not required.

User Response: User action above.
CTG9659E Unable to build security
information to pass to
LogonLogoff class
Explanation: The resource adapter was unable
to create a Subject object required to be passed to
the registered LogonLogoff class. This could be
because the required Java Security permissions
are not available.
System Action: System action is not required.
User Response: User action above.
CTG9660E No Connection Manager passed to
resource adapter. Adapter unable
to function
Explanation: A Request to create a connection
factory has failed because a null connection
manager was passed to the
createConnectionFactory method.
System Action: System action is not required.
User Response: User action above.
CTG9661I EPI is not transactional, so this
action is not supported
Explanation: The EPI resource adapter does not
support any transactional interfaces. Any attempt
to use them will throw an exception.
System Action: System action is not required.
User Response: User action above.
CTG9662I You can only have one interaction
per connection
Explanation: The EPI resource adapter only
supports a single EPIInteraction instance per
EPIConnection instance.
System Action: System action is not required.
User Response: Because a connection represents
a 3270 conversation, only one interaction per
connection is allowed.
CTG9659E CTG9666E
CTG9663E A connection which is not the
active connection attempted to
execute on the resource adapter.
Explanation: The EPIConnection that your
component is trying to use is not the current
Connection being processed by the EPI resource
adapter. The current working Connection must
be closed before work can continue. This is an
internal error.
System Action: System action is not required.
User Response: User action above.
CTG9664E Transaction ended. Unable to
determine server state.
Explanation: The CICS transaction has ended,
but it is not possible to determine if resources
were committed or rolled back.
System Action: System action is not required.
User Response: User action above.
CTG9665E ExecuteTimeout property cannot
be negative.
Explanation: The ExecuteTimeout property on
the ECIInteractionSpec must be a positive value.
System Action: System action is not required.
User Response: User action above.
CTG9666E Value of InteractionVerb is not
one of SYNC_SEND,
SYNC_RECEIVE,
SYNC_SEND_RECEIVE.
Explanation: You have not passed a valid value
for InteractionVerb within your
ECIInteractionSpec.
System Action: System action is not required.
User Response: User action above.
Messages 119

CTG9667E CTG9801E
CTG9667E FunctionName is empty, cannot
send request.
Explanation: In order to carry out an Interaction
with CICS a FunctionName must be provided in
the ECIInteractionSpec. This FunctionName maps
to the program that is to be executed on the
CICS server.
System Action: System action is not required.
User Response: The function name in the
ECIInteractionSpec is empty, request not valid.
CTG9671E Screenable input record doesn’t
match the current screen
definition
Explanation: The input record provided does
not match the EPI resource adapter’s
representation of the screen.
System Action: System action is not required.
User Response: User action above.
CTG9673E SYNC_RECEIVE required
Commarea length, reply length or
both to be defined.
Explanation: A SYNC_RECEIVE interaction
requires the COMMAREA length or reply length
to be specified in the InteractionSpec, and neither
have been specified.
System Action: System action is not required.
User Response: User action above.
CTG9674E No SSL keyring class was
provided for SSL protocol
Explanation: The SSL protocol was specified for
the connectionURL, but no keyring has been
specified.
System Action: System action is not required.
User Response: No SSL keyring class was
provided for SSL protocol.
120 CICS Transaction Gateway: CICS Transaction Gateway Messages
CTG9675E EPI resource adapter failed trying
to populate Screenable record
Explanation: An exception was thrown by the
screenable record when the EPI resource adapter
attempted to populate it with the relevant
information. The record exception is linked to
this one.
System Action: System action is not required.
User Response: User action above.
CTG9676E IOException occurred when
reading the Input Record.
Explanation: An I/O exception was thrown by
the record when the resource adapter attempted
to read the information. The record exception is
linked to this one.
System Action: System action is not required.
User Response: User action above.
CTG9800E No message for id {0} could be
located
Explanation: The message id indicated could
not be located within the message file.
System Action: No action taken.
User Response: Contact your service
representative with the information.
CTG9801E A request to get or set an attribute
was unknown to MBean {0}
Explanation: A Management Bean received a
request to get or set an attribute but this attribute
is unknown to it.
System Action: No action taken.
User Response: Ensure the management bean
being invoked supports this attribute.

CTG9802E An invalid value was given for an
attribute for MBean {0}
Explanation: A request to set an attribute on a
management bean failed because the value
provided was not valid.
System Action: The attribute doesn’t change.
User Response: Ensure the value provided is
valid for the attribute.
CTG9803E An unexpected exception was
received from MBean {0}
Explanation: A management bean throw an
exception which was not expected by the system.
System Action: No action taken.
User Response: The linked exception may
provide more information on the problem.
CTG9804E An unknown exception occurred
whilst trying to set the trace file
to {0}
Explanation: An exception occurred whilst
trying to set the Gateway trace file to the
specified file. This might be because the specified
file is a directory, is not writeable or cannot be
opened for another reason.
System Action: The Gateway trace file is not
changed.
User Response: Check that the file specified is a
valid file and is in a writeable location.
CTG9805E An unknown exception occurred
whilst trying to set the jni trace
file to {0}
Explanation: An exception occurred whilst
trying to set the JNI trace file to the specified file.
This might be because the specified file is a
directory, is not writeable or cannot be opened
for another reason.
System Action: The JNI trace file is not
changed.
User Response: Check that the file specified is a
valid file and is in a writeable location.
CTG9802E CTG9809E
CTG9806E An error occurred when setting {0}
Explanation: When trying to make multiple
changes to the Gateway server {0} failed.
System Action: The Gateway server settings are
not changed.
User Response: Check that the parameters used
in the change are correct.
CTG9807E Attempted to Rollback due to
error setting {0}. Error occurred
during rollback because of setting
{1}
Explanation: When trying to make multiple
changes to the Gateway server {0} failed. Then
when trying to undo the changes already made,
a further change {1} failed.
System Action: The Gateway server settings are
left in an undefined state.
User Response: Check that the parameters used
in the change are correct.
CTG9808E The value of {1} is not valid for {0}
Explanation: When trying to change a Gateway
trace setting, the value provided was not valid.
System Action: The Gateway server setting is
not changed.
User Response: Check that the value used for
the setting is correct.
CTG9809E The value of {1} is not valid for {0}
Explanation: When trying to change a Gateway
JNI trace setting, the value provided was not
valid.
System Action: The Gateway server setting is
not changed.
User Response: Check that the value used for
the setting is correct.
Messages 121

CTG9810E CTG9815E
CTG9810E The trace file {0} specified a
directory
Explanation: When trying to set the Gateway
trace file, the value specified a directory.
System Action: The trace file is not changed.
User Response: Specify a trace file that is not a
directory.
CTG9811E The trace file {0} specified an
invalid path
Explanation: When trying to set the Gateway
trace file, the value specified an invalid path.
System Action: The trace file is not changed.
User Response: Specify a trace file using a valid
path for the platform.
CTG9812E The trace file {0} specified an
unwriteable file
Explanation: When trying to set the Gateway
trace file, the value specified a file on which the
Gateway does not have write permissions, or a
directory in which the Gateway cannot create or
write a file.
System Action: The trace file is not changed.
User Response: Specify a trace file which is
writeable by the Gateway or in a location which
is writeable by the Gateway.
CTG9814E The jni trace file {0} specified an
invalid path
Explanation: When trying to set the jni trace
file, the value specified an invalid path.
System Action: The jni trace file is not changed.
User Response: Specify a jni trace file using a
valid path for the platform.
CTG9815E The jni trace file {0} specified an
unwriteable file
Explanation: When trying to set the jni trace
file, the value specified a file on which the CTG
122 CICS Transaction Gateway: CICS Transaction Gateway Messages
does not have write permissions, or a directory
in which the CTG cannot create or write a file.
System Action: The jni trace file is not changed.
User Response: Specify a trace file which is
writeable by the CTG or in a location which is
writeable by the CTG.

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The product library and related literature
This chapter lists books on the CICS Transaction Gateway, and related topics.
It also discusses how you can view the online library supplied with the
product.
It consists of the following topics:
“CICS Transaction Gateway books” Read this for a list of all books provided
with the CICS Transaction Gateway.
“Sample configuration documents” on
page 124
Read this for information about a series of
PDF documents that provide step-by-step
guidance on configuring the CICS
Transaction Gateway.
“Redbooks ” on page 125 Read this for details of other publications
that contain examples of client/server
configurations.
“Other Useful Books” on page 125 Read this for details of other relevant
publications.
“Obtaining books from IBM” on page 126 Read this for information on downloading
books and ordering hardcopy versions.
CICS Transaction Gateway books
v CICS Transaction Gateway: Windows ® Administration, SC34-6190
This book describes the administration of the CICS Transaction Gateway for
Windows.
v CICS Transaction Gateway: UNIX ® Administration, SC34-6139
This book describes the administration of the CICS Transaction Gateway for
UNIX operating systems.
v CICS Transaction Gateway: z/OS ® Administration, SC34-6191
This book describes the administration of the CICS Transaction Gateway for
z/OS.
v CICS Transaction Gateway: Gateway Messages
This online book lists and explains the error messages that can be generated
by CICS Transaction Gateway.
You cannot order this book.
v CICS Transaction Gateway: Programming Reference, SC34-6140
© Copyright IBM Corp. 1994, 2002 123

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The CICS Transaction Gateway
This book provides information on the APIs of the programming languages
supported by the CICS Transaction Gateway.
There are also additional HTML pages that contain JAVA programming
reference information.
v CICS Transaction Gateway: Programming Guide, SC34-6141
This introduction to programming for the CICS Transaction Gateway
provides the information that you need to allow non-CICS applications to
use CICS facilities in a client/server environment.
Sample configuration documents
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. .
The following scenarios are currently covered:
v Configuring CICS Transaction Gateway for Windows for Microsoft ® SNA
Server
v Configuring CICS Transaction Gateway for Windows for eNetwork Personal
Communications
v Configuring CICS Transaction Gateway for Windows for TCP62
v Configuring CICS Transaction Gateway for AIX ® for IBM ® eNetwork
Communications Server
v Configuring CICS Transaction Gateway for Windows for Communications
Server
v Configuring CICS Transaction Gateway for Terminal Servlets using
WebSphere ® Application Server for Windows
v Client security configuration
v Configuring CICS Transaction Gateway for WebSphere 4.01 using J2EE
v Configuring CICS Transaction Gateway 4.02 for WebSphere Application
Server on z/OS using J2EE
As more sample configuration documents become available, you can
download them from our Web site at:
www.ibm.com/software/ts/cics/
and follow the Download link.
124 CICS Transaction Gateway: CICS Transaction Gateway Messages

Redbooks
Other Useful Books
The following International Technical Support Organization (ITSO) Redbook
publication contains many examples of client/server configurations:
v CICS Transaction Gateway V3.1 The WebSphere Connector for CICS, SG24-6133
This book supersedes the following book:
v Revealed! CICS Transaction Gateway with more CICS Clients Unmasked,
SG24-5277.
v Java Connectors for CICS: Featuring the J2EE Connector Architecture, SG24-6401.
This book provides information on developing J2EE applications.
See also:
v Securing Web Access to CICS, SG24–5756.
v Workload Management for Web Access to CICS, SG24–6118.
You can obtain ITSO Redbooks from a number of sources. For the latest
information, see:
www.ibm.com/redbooks/
CICS Transaction Server publications
Other publications
CICS interproduct communication
The following books describe the intercommunication facilities of the CICS
server products:
CICS Family: Interproduct Communication, SC34-6030
Transaction Server for Windows NT ® : Intercommunication, SC33-1882
CICS Transaction Server for z/OS: Intercommunication Guide, SC34-6005
CICS Transaction Server for VSE/ESA : Intercommunication Guide, SC33-1665
CICS for OS/400 ® : Intercommunication, SC33-1388
TXSeries: CICS Intercommunication Guide, SC09-3900
CICS for OS/2: Intercommunication, SC33-1583
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:
Transaction Server for Windows NT: Problem Determination, GC33-1883
CICS Transaction Server for z/OS ® Problem Determination Guide, SC34-6002
The product library and related literature 125

Other publications
CICS Transaction Server for VSE/ESA Problem Determination Guide,
GC33-1663
CICS for OS/400 ® : Problem Determination, SC33-1384
TXSeries: CICS Problem Determination Guide, SC33-1565.
You can find information on CICS products at the following Web site:
www.ibm.com/software/ts/cics/
APPC-related publications
The following books are concerned with products providing APPC support:
IBM products
IBM Communications Server for AIX for AIX:
IBM Communications Server for AIX: Quick Beginnings, GC31-8583
IBM Communications Server for AIX: General Information, GC31-8584
IBM Communications Server for AIX: Administration, SC31-8586
IBM Communications Server for AIX: Administration Command Reference,
SC31-8587
Systems Network Architecture (SNA)
SNA Formats, GA27-3136
Systems Network Architecture Technical Overview, GC30-3073
TCP62–related publications
Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
GC31–7073
Multiprotocol Transport Networking (MPTN) Architecture: Formats, GC31–7074
Obtaining books from IBM
For information on books you can download, visit our Web site at:
www.ibm.com/software/ts/cics/
and follow the Library link.
You can order hardcopy books:
v Through your IBM representative or the IBM branch office serving your
locality.
v By calling 1-800-879-2755 in the United States.
v From the Web site at:
www.ibm.com/shop/publications/order
126 CICS Transaction Gateway: CICS Transaction Gateway Messages

|
|
|
|
|
|
|
|
|
|
Accessibility
The English version of the CICS Transaction Gateway has been tested for
accessibility on the Windows operating system. The product is accessible.
Documentation
Download the CICS Information Center for an html version of the
documentation. Go to this Web page
www.ibm.com/software/ts/cics/
and follow the Library link.
© Copyright IBM Corp. 1994, 2002 127

128 CICS Transaction Gateway: CICS Transaction Gateway Messages

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.
A
abend. The termination of a task, job, or
subsystem because of an error condition that
recovery facilities cannot resolve.
APAR. (Authorized program analysis report.) A
report on the basis of which IBM supplies a fix
of a temporary corrective nature to elements of
function SYSMODs. APAR fixes are called
″corrective″ service because they are installed to
cure problems currently being experienced by an
installation. The APAR fix is usually in the form
of either a modification to a load module or an
update to card-image data. It is intended as a
temporary arrangement until a preventive service
(PTF) is issued to fix the problem permanently.
This PTF supersedes the APAR fix, and indeed
specifies this relationship on its ++VER
statement.
API. Application programming interface.
APING. A command used to verify an APPC
link.
APPC. Advanced program-to-program
communication. 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.
applet. A Java program that is downloaded to,
and executed on, a Web browser or network
computer. See also servlet.
applid. In CICS, a system initialization and
terminal control parameter that identifies the
CICS system to other remote systems.
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 facility that enables terminal
definitions to be created automatically in a CICS
server on request. The definition is deleted when
the client terminal is logged off.
automatic transaction initiation (ATI). The
process whereby a transaction request made
internally within a CICS system or network leads
to the scheduling of the transaction. An ATI
request from a CICS Transaction Gateway can
cause the initiation of a transaction in a CICS
server system.
B
beans. See JavaBeans .
BIND. 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.
C
CA. See certification authority.
CEDA. A CICS transaction that defines
resources online.
© Copyright IBM Corp. 1994, 2002 129

Glossary
certification authority. In computer security, an
organization that issues certificates. The
certification 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 External Call Interface (EXCI). An
application programming interface that enables a
program running on Z/OS, such as CICS
Transaction Gateway, to call a program running
in a CICS region. The programs can transfer data
between each other using a communication area.
Compare with External Call Interface (ECI).
CICS Gateway for Java. In CICS Universal
Clients Version 2, an interface between a Java
program and CICS that allows a Java-enabled
browser to dynamically download a Java Applet
and transparently access CICS data. This has
been replaced by the CICS Transaction Gateway.
CICS on open systems. A term used to refer
generically to the products: CICS for HP-UX,
CICS for Sun Solaris, TXSeries for AIX,
TXSeries for HP-UX, and TXSeries for Solaris.
CICS on System/390 ® . A term used to refer
generically to the products CICS Transaction
Server for z/OS , CICS for MVS/ESA ,CICS
Transaction Server for z/OS, CICS Transaction
Server for VSE/ESA, and CICS/VSE ® .
cicscli. A command that starts and stops the
Client daemon, checks the availability of servers,
and sets other options.
cicsprnt. A command that allows you to define
a printer terminal on the Client daemon
workstation. The command enables CICS
applications running on the server to direct
output to the client-attached printer.
cicsterm. A command that provides 3270
emulation and enables connection to a CICS
region.
130 CICS Transaction Gateway: CICS Transaction Gateway Messages
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. An environment variable that tells
the JVM and other Java applications where to
find the class libraries, including user-defined
class libraries.
Client API. On distributed platforms running
non-Java applications, the interface between the
Client application and the Client daemon.
client application. A user application, written in
a supported programming language other than
Java, that communicates directly with the Client
daemon.
Client daemon. The Client daemon (process
cclclnt) exists only on distributed platforms. 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. A distributed application design
model, in which the client sends a request to its
partner, the server, which executes the request
and returns the results to the client. This design
model is associated typically with cooperative
processing.
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. File CICSCOL.INI used by
the CICS Transaction Gateway to customize the
3270 screen color attributes on client
workstations.
COMMAREA. A communication area that is
used for passing data both between programs
within a transaction and between transactions.

Common Object Request Broker Architecture
(CORBA). An industry standard for an interface
definition language that enables different object
request brokers to interoperate.
configuration file. The file CTG.INI containing
information telling CICS Transaction Gateway
about the CICS servers that it can connect to, and
the communication protocols to use.
configuration tool. A graphical user interface
that allows you to configure the CICS
Transaction Gateway.
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.
control table. In CICS, a storage area used to
describe or define the configuration or operation
of the system.
conversation. The communication between a
CICS Transaction Gateway and a CICS server. In
APPC, a connection between two transaction
programs over an LU-LU session that allows
them to communicate with each other while
processing a transaction. See also session.
conversation security. In APPC, a process that
allows validation of a user ID or group ID and
password before establishing a connection.
cooperative processing. A subset of distributed
processing, in which at least the user interface
(presentation) aspect of the application runs on a
programmable workstation.
CORBA. See Common Object Request Broker
Architecture.
ctgstart. A command that starts the gateway
daemon.
D
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.
Glossary
dependent LU. A logical unit (LU) that can
receive, but not send a BIND, and which
supports only single sessions. See BIND.
digital certificate. A form of personal
identification that can be verified electronically.
Only the certificate owner who holds the
corresponding private key can present a
certificate for authentication through a Web
browser session. Anyone can verify that the
certificate is valid by using a readily available
public key.
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. A link that enables
an application program running on one CICS
system to link to another application program
running in another CICS system.
Glossary 131

Glossary
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.
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.
E
EBCDIC. Extended binary-coded decimal
interchange code. A coded character set of 256
8-bit characters developed for the representation
of textual data.
ECI. See external call interface.
emulator, 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. In the CICS Transaction
Gateway the terminal emulation function allows
client workstations to run CICS transactions that
use 3270 data flows.
132 CICS Transaction Gateway: CICS Transaction Gateway Messages
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.
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 10–megabit or 100–megabit
baseband 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 CICS External Call Interface.
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.
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.
F
firewall. A configuration of software that
prevents unauthorized traffic between a trusted
network and an untrusted network.

G
gateway. A device that connects two dissimilar
LANs, or that connects a LAN to a wide area
network (WAN), midrange computer, or
mainframe computer. A gateway device has its
own processor and memory and may perform
protocol conversion. A gateway handles multiple
communication sessions simultaneously.
gateway classes. The interface for Java Client
applications to connect to the Gateway daemon.
The Gateway classes, which are supplied with
the CICS Transaction Gateway, must be in the
classpath for Java Client applications to run.
gateway daemon. Used only in remote mode,
the Gateway daemon listens on protocols defined
in CTG.INI for gateway requests from remote
Java client applications. It issues these requests to
the Client daemon on distributed platforms, and
directly to CICS over the EXCI on z/OS. The
Gateway daemon runs the protocol listener
threads, the worker threads and the connection
manager threads. It uses the GATEWAY section
of CTG.INI (and on z/OS the ctgenvvar script)
for its configuration.
H
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 in an internet.
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
domain name of a host.
HTTP. In the Internet suite of protocols, the
protocol that is used to transfer and display
hypertext and XML documents.
HTTPS. A TCP/IP protocol that World Wide
Web servers and Web browsers use to transfer
and display documents secured by SSL.
I
iKeyman. A tool supplied with the Gateway for
maintaining digital certificates for SSLight and
JSSE.
independent LU. A logical unit (LU) that can
both send and receive a BIND, and which
supports single, parallel, and multiple sessions.
See BIND.
internet. A collection of networks
interconnected by a set of routers that allow
them to function as a single, large network.
Contrast with Internet.
Internet. The internet administered by the
Internet Architecture Board (IAB), consisting of
large national backbone networks and many
regional and campus networks all over the
world. The Internet uses the Internet suite of
protocols.
Internet address. See IP address.
Glossary
Internet Architecture Board. The technical body
that oversees the development of the internet
suite of protocols known as TCP/IP.
Internet Packet Exchange (IPX). In Novell
NetWare LANs, a communication protocol that
sends data packets to requested destinations.
Internet Protocol (IP). In TCP/IP, a protocol
that routes data from its source to its destination
in an Internet environment.
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.
intranet. A private network that integrates
Internet standards and applications (such as Web
browsers) with an organization’s existing
Glossary 133

Glossary
computer networking infrastructure. Compare
with Internet and internet.
IP. Internet Protocol.
IPX. Internet Packet Exchange.
J
J2EE. (Java 2 Platform, Enterprise Edition.) 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.
Java. An object-oriented programming language
for portable interpretive code that supports
interaction among remote objects.
JavaBeans. A platform-independent, software
component technology for building reusable Java
components called beans. Once built, these beans
can be made available for use by other software
engineers or they can be used in Java
applications. Also, using JavaBeans, software
engineers can manipulate and assemble beans in
a graphical drag-and-drop development
environment.
Java client application. A Java application,
servlet or applet that communicates with the
Gateway classes.
Java development kit (JDK). A software
package that can be used to write, compile,
debug, and run Java applets and applications.
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 Secure Socket Extension (JSSE). An
implementation of SSL, written in Java, and
supported by CICS Transaction Gateway.
134 CICS Transaction Gateway: CICS Transaction Gateway Messages
Java Virtual Machine (JVM). A software
implementation of a processor that runs
compiled Java code (applets and applications).
JDK. See Java development kit (JDK).
JNI. See Java Native Interface (JNI).
JSSE. See Java Secure Socket Extension (JSSE).
JVM. See Java Virtual Machine (JVM).
K
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. The default keyboard mapping file for
the CICS Transaction Gateway is CICSKEY.INI.
KeyRing or KeyStore. In computer security, a
file that contains public keys, private keys,
trusted roots, and certificates.
L
LAN. See local area network.
local area network (LAN). A network of
workstations, or terminals, or both, where all the
connected systems are relatively near to each
other. See wide area network.
local mode. Describes a Java Client application
using the Gateway local protocol. The Gateway
daemon is not used in local mode; on distributed
platforms, the Gateway classes interface directly
with the Client daemon API, and with the EXCI
on z/OS. See remote mode.
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.
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.
LU-LU session type 6.2. In SNA, a type of
session for communication between peer
systems. Synonymous with APPC protocol.
LU 6.2. See APPC.
M
MAC. Medium access control.
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.
N
name server. In TCP/IP, synonym for Domain
Name Server In Internet communications, the
host that translates host names into their
respective internet addresses when requested by
the hosts on the network A physical device, and
its associated software, that enables a processor
or controller to be connected to a network.
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.
O
object. In object-oriented programming, a
concrete realization of a class that consists of
data and the operations associated with that
data.
object request broker (ORB). Software that
serves as an intermediary by transparently
enabling objects to exchange requests and
responses.
OO. Object-oriented.
P
Glossary
pacing. A technique by which a receiving
station controls the rate of transmission of a
sending station to prevent overrun.
packet internet groper (PING). In Internet
communications, a program used in TCP/IP
networks to test the ability to reach destinations
Glossary 135

Glossary
by sending the destinations an Internet Control
Message Protocol (ICMP) echo request and
waiting for a reply.
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. Packet internet groper. The command
that sends an ICMP Echo Request packet to a
gateway, router, or host with the expectation of
receiving 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. Primary logical unit. 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.
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 (LU) that contains the primary half-session
for a particular LU-LU session. Contrast with
secondary logical unit. See also logical unit.
Note: A particular logical unit may contain
primary and secondary half-sessions for
different active LU-LU sessions.
protocol boundary. The signals and rules
governing interactions between two components
within a node.
136 CICS Transaction Gateway: CICS Transaction Gateway Messages
R
RACF ® . Resource Access Control Facility. An
IBM licensed program that provides access
control by identifying users to the system;
verifying users of the system; authorizing access
to protected resources; logging detected,
unauthorized attempts to enter the system; and
logging detected accesses to protected resources.
region. A physical instance of a CICS server.
remote mode. Describes a Java Client
application using a Gateway network protocol to
connect to the Gateway daemon. See local mode.
remote procedure call (RPC). Remote procedure
calls are analogous to the standard procedure
calls used in modern programming, providing
modularity and reducing code size. The main
difference between standard procedure calls and
remote procedure calls is that in a remote
procedure call, the called procedure is being
executed by a different process than the caller. To
the calling procedure, a remote procedure call
looks the same as a call to a local procedure.
When a program makes a remote procedure call
to a remote application, the procedure’s
parameters are automatically bundled into a
request message, which is then sent to the
remote program or system.
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.
RU. Request unit. Response unit.

RPC. See remote procedure call.
S
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.
servlet. A Java servlets program that run on a
Web server machine, unlike Java applets, which
are downloaded to a Web browser. Java servlets
have become popular as a replacement for CGI
(Common Gateway Interface) programs.
session. In SNA, a logical connection between
two network addressable units (NAUs) that can
be activated, tailored to provide various
protocols, and deactivated as requested. The
session activation request and response can
determine options for such things as rate and
concurrency of data exchange, control of
contention and error recovery, and characteristics
of the data stream. Sessions compete for network
resources, such as links within the path control
network. For routing purposes, each session is
identified by the network or local addresses of
the session partners. See LU-LU session, LU-LU
session type.
session limit. In SNA, the maximum number of
concurrently active LU-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.
signon capable terminal. A signon capable
terminal allows signon transactions, either
CICS-supplied (CESN) or user-written, to be run.
Contrast with signon incapable terminal.
SIT (system initialization table). A table
containing parameters used to start a CICS
control region.
SNA gateway. A gateway that handles multiple
APPC communication sessions simultaneously.
See gateway.
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.
SSL. See Secure Sockets Layer (SSL).
Glossary
SSLight. An implementation of SSL, written in
Java, and supported by CICS Transaction
Gateway.
System Management Interface Tool (SMIT). In
the AIX operating system, a set of menu-driven
services that facilitate the performance of system
tasks such as installation, management,
configuration, and diagnosis.
standard error. In many workstation-based
operating systems, the output stream to which
error messages or diagnostic messages are sent.
subnet. In TCP/IP, a part of a network that is
identified by a portion of the Internet address.
Synonym for subnetwork.
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.
Systems Network Architecture (SNA). The
description of the logical structure, formats,
protocols, and operational sequences for
Glossary 137

Glossary
transmitting information units through, and
controlling the configuration and operation of,
networks.
System SSL. An implementation of SSL,
supported by CICS Transaction Gateway on
z/OS. Written in native code, it supports
hardware encryption technology available to
z/OS, and can be used only for SSL servers on
that operating system.
T
Taskguide. A function of the configuration tool
that provides step-by-step guidance to
configuring your CICS Transaction Gateway. .
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. Transmission Control Protocol/Internet
Protocol.
TCP/IP address. An address that uniquely
identifies a machine on a network. A machine
can have several threads of execution running at
the same time; a TCP/IP port uniquely identifies
a particular thread.
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.
Terminal Servlet. A Java program that allows
you to use a Web browser as an emulator for a
3270 CICS application running on any CICS
server.
thread. A stream of computer instructions that
is in control of a process. A multithread process
begins with one stream of instructions (one
thread) and may later create other instruction
streams to perform tasks.
138 CICS Transaction Gateway: CICS Transaction Gateway Messages
token ring. A network with a ring topology that
passes tokens from one attaching device to
another; for example, the IBM Token-Ring
network.
trace. A record of data that provides a history of
events that occurred in a system. The process of
recording the sequence in which the statements
in a program are executed and, optionally, are
the values of the program variables used in the
statements.
transaction program. A program that uses the
APPC application program interface (API) to
communicate with a partner application program
in the same node or at a partner node.
Transmission Control Protocol/Internet Protocol
(TCP/IP). A set of communications protocols
that support peer-to-peer connectivity functions
for both local and wide area networks. TCP/IP
can be used for client/server links between the
Client daemon and, for example, CICS for
OS/2 ® , CICS for Windows NT.
type 2.0 node. An SNA node that attaches to a
subarea network as a peripheral node and
provides full 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.
U
URL. (Uniform Resource Locator.) 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.
user session. Any APPC session other than a
SNASVCMG session.

V
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.
W
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.
Glossary
Glossary 139

Glossary
140 CICS Transaction Gateway: CICS Transaction Gateway Messages

Index
A
accessibility 127
B
books 123
CICS Transaction Gateway 123
D
disability 127
documentation 123
G
glossary of terms and abbreviations 129
P
publications, CICS Transaction Gateway 123
© Copyright IBM Corp. 1994, 2002 141

142 CICS Transaction Gateway: CICS Transaction Gateway Messages

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.
© Copyright IBM Corp. 1994, 2002 143

Trademarks
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 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:
CICS IBM
Java and all Java-based trademarks and logos are trademarks of Sun
Microsystems, Inc. in the United States, or other countries, or both.
Other company, product or service names may be trademarks or service
marks of others.
144 CICS Transaction Gateway: CICS Transaction Gateway Messages

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. 1994, 2002 145

����
Program Number: 5724-D12
Printed in U.S.A.
SC34-6193-00

Spine information:
��� CICS Transaction Gateway CICS Transaction Gateway Messages Version 5.0